@equationalapplications/core-llm-wiki 7.2.1 → 7.3.0

package/dist/testing.js

@@ -621,6 +621,17 @@ function validateTask(task) {
     priority
   };
 }
+function factRejectionReason(raw) {
+  const fact = raw;
+  if (typeof fact?.title !== "string" || typeof fact?.body !== "string") return "invalid_shape";
+  if (!clip(fact.title, 80)) return "missing_title";
+  return "missing_body";
+}
+function taskRejectionReason(raw) {
+  const task = raw;
+  if (typeof task?.description !== "string") return "invalid_shape";
+  return "missing_description";
+}
 function normalizeSourceRef(value) {
   if (typeof value !== "string") return null;
   const cleaned = value.replace(/[^A-Za-z0-9._\- ]/g, "").trim().slice(0, 255);
@@ -644,6 +655,104 @@ function jaccardScore(a, b) {
 var DEFAULT_MAX_EMBED_CHARS = 6e3;
 var EMBED_CHARS_CEILING = 16e3;
 
+// src/utils/diagnostics.ts
+var SEVERITY = {
+  ingest_chunk_failed: "warn",
+  fact_rejected: "warn",
+  task_rejected: "warn",
+  fact_deduplicated: "info",
+  edge_dropped: "warn",
+  embedding_failed: "warn",
+  hook_failed: "warn",
+  background_job_failed: "error",
+  heal_skipped: "warn",
+  grounding_missing: "warn",
+  grounding_failed: "warn",
+  classification_low_confidence: "info",
+  classification_invalid: "warn"
+};
+var MESSAGE = {
+  ingest_chunk_failed: "One or more document chunks failed to parse or generate.",
+  fact_rejected: "An extracted fact failed validation and was not written.",
+  task_rejected: "An extracted task failed validation and was not written.",
+  fact_deduplicated: "An extracted fact duplicated an existing fact and was not written.",
+  edge_dropped: "An extracted edge could not be resolved against the ontology and was not written.",
+  embedding_failed: "A fact could not be embedded.",
+  hook_failed: "A host hook threw or rejected.",
+  background_job_failed: "A background maintenance job failed.",
+  heal_skipped: "Heal skipped a candidate fact.",
+  grounding_missing: "A fact carried no qualifying evidence and was stored as a draft.",
+  grounding_failed: "A fact carried evidence not found in its source and was stored as a draft.",
+  classification_low_confidence: "A classifier answer was below the confidence threshold and was not applied.",
+  classification_invalid: "A classifier answer was invalid and was not applied."
+};
+var warnedNonFunction = /* @__PURE__ */ new WeakSet();
+function copyDetail(detail) {
+  const copy = { ...detail };
+  if (detail.chunkIndexes) copy.chunkIndexes = detail.chunkIndexes.slice();
+  return copy;
+}
+function emitDiagnostic(options, input) {
+  const hook = options.onDiagnostic;
+  if (hook === void 0 || hook === null) return;
+  if (typeof hook !== "function") {
+    if (!warnedNonFunction.has(options)) {
+      warnedNonFunction.add(options);
+      console.warn("[WikiMemory] onDiagnostic is not a function; diagnostics are disabled.");
+    }
+    return;
+  }
+  const diagnostic = {
+    code: input.code,
+    severity: SEVERITY[input.code],
+    operation: input.operation,
+    trigger: input.trigger,
+    entityId: input.entityId,
+    at: Date.now(),
+    message: MESSAGE[input.code],
+    ...input.detail ? { detail: copyDetail(input.detail) } : {}
+  };
+  try {
+    const returned = hook(diagnostic);
+    if (returned !== void 0) {
+      Promise.resolve(returned).catch((err) => {
+        console.warn("[WikiMemory] onDiagnostic hook rejected:", err);
+      });
+    }
+  } catch (err) {
+    console.warn("[WikiMemory] onDiagnostic hook threw:", err);
+  }
+}
+var DiagnosticBuffer = class {
+  constructor() {
+    this.items = [];
+  }
+  push(input) {
+    this.items.push(input);
+  }
+  get size() {
+    return this.items.length;
+  }
+  flush(options) {
+    const pending = this.items;
+    this.items = [];
+    for (const input of pending) emitDiagnostic(options, input);
+  }
+  discard() {
+    this.items = [];
+  }
+};
+function edgeDropDiagnostic(drop, ctx) {
+  const detail = { reason: drop.reason };
+  const factId = ctx.factId ?? drop.sourceId;
+  if (factId) detail.factId = factId;
+  if (drop.edgeType) detail.edgeType = drop.edgeType;
+  if (drop.sourceNodeType) detail.sourceNodeType = drop.sourceNodeType;
+  if (drop.targetNodeType) detail.targetNodeType = drop.targetNodeType;
+  if (ctx.sourceRef) detail.sourceRef = ctx.sourceRef;
+  return { code: "edge_dropped", operation: ctx.operation, trigger: ctx.trigger, entityId: ctx.entityId, detail };
+}
+
 // src/services/EmbeddingService.ts
 var EmbeddingService = class {
   constructor(db, options, entryRepo, metadataRepo) {
@@ -707,7 +816,7 @@ var EmbeddingService = class {
       });
     }
   }
-  async tryEmbedFact(fact) {
+  async tryEmbedFact(fact, ctx) {
     const embedFn = this.options.llmProvider.embed;
     if (typeof embedFn !== "function") return { ok: false, kind: "no_provider" };
     let tagsStr;
@@ -729,6 +838,7 @@ var EmbeddingService = class {
       const vector = await embedFn(text);
       if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
         console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
+        this.reportEmbed(ctx, fact, "embedding_failed", "invalid_vector");
         await this.markFailure(fact.id, "invalid_vector");
         return { ok: false, kind: "invalid_vector" };
       }
@@ -742,11 +852,13 @@ var EmbeddingService = class {
       }
       if (hasNonFinite) {
         console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
+        this.reportEmbed(ctx, fact, "embedding_failed", "float32_overflow");
         await this.markFailure(fact.id, "float32_overflow");
         return { ok: false, kind: "float32_overflow" };
       }
     } catch (err) {
       console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
+      this.reportEmbed(ctx, fact, "embedding_failed", "embed_threw");
       await this.markFailure(fact.id, "provider_error");
       return { ok: false, kind: "provider_error" };
     }
@@ -756,15 +868,31 @@ var EmbeddingService = class {
       await this.entryRepo.updateEmbeddingBlob(fact.id, blob);
     } catch (err) {
       console.warn(`[WikiMemory] embedFact: persisting embedding failed for ${fact.id}:`, err);
+      this.reportEmbed(ctx, fact, "embedding_failed", "persist_failed");
       return { ok: false, kind: "storage_error" };
     }
     try {
       await this.notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
     } catch (hookErr) {
       console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for ${fact.id}:`, hookErr);
+      this.reportEmbed(ctx, fact, "hook_failed", "on_embedding_persisted");
     }
     return { ok: true, dimension: float32Vector.length };
   }
+  reportEmbed(ctx, fact, code, reason) {
+    if (!ctx) return;
+    emitDiagnostic(this.options, {
+      code,
+      operation: ctx.operation,
+      trigger: ctx.trigger,
+      entityId: fact.entity_id,
+      detail: { factId: fact.id, reason }
+    });
+  }
+  /** For callers that invoke `notifyEmbeddingPersisted` directly and catch its failure. */
+  reportHookFailed(ctx, entityId, factId) {
+    this.reportEmbed(ctx, { id: factId, entity_id: entityId }, "hook_failed", "on_embedding_persisted");
+  }
   /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
   async markFailure(id, kind) {
     try {
@@ -778,8 +906,8 @@ var EmbeddingService = class {
    * ImportExportService branch on `if (!embedded)`; a discriminated result
    * object is always truthy and would silently disable that branch.
    */
-  async embedFact(fact) {
-    const result = await this.tryEmbedFact(fact);
+  async embedFact(fact, ctx) {
+    const result = await this.tryEmbedFact(fact, ctx);
     return result.ok;
   }
   async notifyEmbeddingPersisted(entityId, factId, vector) {
@@ -1192,7 +1320,7 @@ var ImportExportService = class {
           title: clipped?.title ?? fact.title,
           body: clipped?.body ?? fact.body,
           tags: Array.isArray(fact.tags) || typeof fact.tags === "string" ? fact.tags : []
-        });
+        }, { operation: "importDump", trigger: "call" });
         if (!embedded) {
           await this.embeddingService.notifyEmbeddingPersisted(entityId, fact.id, null);
         }
@@ -1217,6 +1345,11 @@ var ImportExportService = class {
             `[WikiMemory] onEmbeddingPersisted hook failed for preserved-blob fact ${fact.id}:`,
             hookErr
           );
+          this.embeddingService.reportHookFailed(
+            { operation: "importDump", trigger: "call" },
+            entityId,
+            fact.id
+          );
         }
       }
     }
@@ -1233,6 +1366,11 @@ var ImportExportService = class {
             `[WikiMemory] onEmbeddingPersisted(vector=null) hook failed for soft-deleted fact ${factId}:`,
             hookErr
           );
+          this.embeddingService.reportHookFailed(
+            { operation: "importDump", trigger: "call" },
+            entityId,
+            factId
+          );
         }
       }
     }
@@ -1628,9 +1766,24 @@ var IngestionService = class {
           try {
             const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
             const result2 = parseJsonResponse(responseText);
+            const rawFacts = Array.isArray(result2.facts) ? result2.facts : [];
+            const facts = [];
+            const itemIndexes = [];
+            const rejected = [];
+            rawFacts.forEach((raw, itemIndex) => {
+              const valid = validateFact(raw);
+              if (valid) {
+                facts.push(valid);
+                itemIndexes.push(itemIndex);
+              } else {
+                rejected.push({ itemIndex, reason: factRejectionReason(raw) });
+              }
+            });
             return {
               status: "ok",
-              facts: (Array.isArray(result2.facts) ? result2.facts : []).map(validateFact).filter((f) => f !== null),
+              facts,
+              itemIndexes,
+              rejected,
               ontology_updates: result2.ontology_updates
             };
           } catch (e) {
@@ -1675,23 +1828,48 @@ var IngestionService = class {
       const failures = [];
       const seen = /* @__PURE__ */ new Set();
       const orderedChunkFacts = [];
-      for (const slot of chunkResults) {
+      const diagBuffer = new DiagnosticBuffer();
+      const diagBase = { entityId, operation: "ingest", trigger: "call" };
+      for (const [chunkIndex, slot] of chunkResults.entries()) {
         if (slot.status === "failed") {
           failedChunks++;
           failures.push(slot.error);
           continue;
         }
         ingestedChunks++;
+        for (const r of slot.rejected) {
+          diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { sourceRef, chunkIndex, itemIndex: r.itemIndex, reason: r.reason } });
+        }
         const dedupedFacts = [];
-        for (const fact of slot.facts) {
+        slot.facts.forEach((fact, k) => {
           const normalizedTitle = normalizeTitleKey(fact.title);
           if (!seen.has(normalizedTitle)) {
             seen.add(normalizedTitle);
             dedupedFacts.push(fact);
+          } else {
+            diagBuffer.push({
+              ...diagBase,
+              code: "fact_deduplicated",
+              detail: { sourceRef, chunkIndex, itemIndex: slot.itemIndexes[k], reason: "exact_title" }
+            });
           }
-        }
+        });
         orderedChunkFacts.push({ facts: dedupedFacts, ontology_updates: slot.ontology_updates });
       }
+      for (const reason of ["parse", "llm"]) {
+        const ofReason = failures.filter((f) => f.source === reason);
+        if (ofReason.length === 0) continue;
+        diagBuffer.push({
+          ...diagBase,
+          code: "ingest_chunk_failed",
+          detail: {
+            sourceRef,
+            reason,
+            count: ofReason.length,
+            chunkIndexes: ofReason.map((f) => f.chunkIndex).sort((a, b) => a - b).slice(0, 20)
+          }
+        });
+      }
       if (failedChunks === chunks.length) {
         throw new WikiIngestEmptyError({
           parseFailures: failures,
@@ -1704,7 +1882,7 @@ var IngestionService = class {
       try {
         if (failedChunks === 0) {
           const fullResult = await this.db.withTransactionAsync(async (tx) => {
-            return await this.runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx);
+            return await this.runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx, diagBuffer);
           });
           deletedSourceFactIds.push(...fullResult.deletedSourceFactIds);
           insertedFacts.push(...fullResult.insertedFacts);
@@ -1712,7 +1890,7 @@ var IngestionService = class {
           const partialResult = await this.db.withTransactionAsync(async (tx) => {
             const flat = [];
             for (const slot of orderedChunkFacts) flat.push(...slot.facts);
-            return await this.appendPartialFacts(entityId, sourceRef, flat, tx);
+            return await this.appendPartialFacts(entityId, sourceRef, flat, tx, diagBuffer);
           });
           insertedFacts.push(...partialResult.insertedDescriptors);
         }
@@ -1726,6 +1904,7 @@ var IngestionService = class {
         }
         return zeroChunkResult(canonical);
       }
+      diagBuffer.flush(this.options);
       await this.searchService.sync(entityId);
       if (failedChunks === 0) {
         const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
@@ -1734,11 +1913,18 @@ var IngestionService = class {
             await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
           } catch (hookErr) {
             console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+            emitDiagnostic(this.options, {
+              entityId,
+              operation: "ingest",
+              trigger: "call",
+              code: "hook_failed",
+              detail: { factId, reason: "on_embedding_persisted" }
+            });
           }
         }
       }
       for (const fact of insertedFacts) {
-        await this.embeddingService.embedFact(fact);
+        await this.embeddingService.embedFact(fact, { operation: "ingest", trigger: "call" });
       }
       this.searchService.evictCache(entityId);
       const result = {
@@ -1884,6 +2070,19 @@ var IngestionService = class {
       const match = candidates[0];
       if (!match) {
         if (strictEffective) throw new WikiStrictOntologyViolation(entityId, "edge", edge.type);
+        opts?.diag?.buffer.push({
+          entityId,
+          operation: opts.diag.operation,
+          trigger: "call",
+          code: "edge_dropped",
+          detail: {
+            reason: "manifest_violation",
+            factId: edge.sourceId,
+            edgeType: edge.type,
+            ...sourceType ? { sourceNodeType: sourceType } : {},
+            sourceRef: params.sourceRef
+          }
+        });
         continue;
       }
       validEdges.push({
@@ -1924,7 +2123,7 @@ var IngestionService = class {
    * On the partial path the caller never invokes this method; the empty
    * arrays stay empty.
    */
-  async runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx) {
+  async runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx, diagBuffer) {
     const deletedSourceFactIds = [];
     const insertedFacts = [];
     deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
@@ -1949,8 +2148,12 @@ var IngestionService = class {
       }
       for (const fact of facts) {
         const ontologyFact = fact;
-        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false }) ?? { okf_type: null, edges: [] };
         const id = generateId("fact_");
+        const validationDrops = [];
+        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false, drops: validationDrops }) ?? { okf_type: null, edges: [] };
+        for (const drop of validationDrops) {
+          diagBuffer.push(edgeDropDiagnostic(drop, { entityId, operation: "ingest", trigger: "call", sourceRef, factId: id }));
+        }
         hostNodes.push({
           id,
           type: ontologyFact.okf_type ?? "",
@@ -1975,6 +2178,7 @@ var IngestionService = class {
     }
     const hostEdges = [];
     for (const req of rawEdgeRequests) {
+      const resolveDrops = [];
       const resolved = this.ontologyService?.resolveEdges(
         entityId,
         req.sourceId,
@@ -1982,8 +2186,12 @@ var IngestionService = class {
         req.edges,
         manifest,
         titleIndex,
-        now
+        now,
+        resolveDrops
       ) ?? [];
+      for (const drop of resolveDrops) {
+        diagBuffer.push(edgeDropDiagnostic(drop, { entityId, operation: "ingest", trigger: "call", sourceRef }));
+      }
       for (const e of resolved) {
         hostEdges.push({ type: e.edge_type, sourceId: e.source_id, targetId: e.target_id });
       }
@@ -1992,7 +2200,7 @@ var IngestionService = class {
       entityId,
       { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
       tx,
-      { strict: false }
+      { strict: false, diag: { buffer: diagBuffer, operation: "ingest" } }
     );
     return { deletedSourceFactIds, insertedFacts };
   }
@@ -2016,7 +2224,7 @@ var IngestionService = class {
    * Runs INSIDE the caller's `tx`. Does not open a nested transaction.
    * Returns `{ inserted, skippedDuplicate }` for observability.
    */
-  async appendPartialFacts(entityId, sourceRef, dedupedFacts, tx) {
+  async appendPartialFacts(entityId, sourceRef, dedupedFacts, tx, diagBuffer) {
     const liveIds = await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false);
     const liveFacts = liveIds.length === 0 ? [] : await this.entryRepo.findByIds(liveIds, void 0, tx);
     const liveTitles = new Set(liveFacts.map((f) => normalizeTitleKey(f.title)));
@@ -2027,6 +2235,13 @@ var IngestionService = class {
     for (const fact of dedupedFacts) {
       const normalizedTitle = normalizeTitleKey(fact.title);
       if (liveTitles.has(normalizedTitle)) {
+        diagBuffer.push({
+          entityId,
+          operation: "ingest",
+          trigger: "call",
+          code: "fact_deduplicated",
+          detail: { sourceRef, reason: "exact_title" }
+        });
         skippedDuplicate++;
         continue;
       }
@@ -2455,7 +2670,7 @@ var MaintenanceService = class {
             permanentlyFailed++;
             continue;
           }
-          const result = await this.embeddingService.tryEmbedFact(row);
+          const result = await this.embeddingService.tryEmbedFact(row, { operation: "reembed", trigger: "call" });
           if (result.ok) embedded++;
           else failed++;
         }
@@ -2576,7 +2791,7 @@ var MaintenanceService = class {
     return { deleted: { entries, tasks: 0 } };
   }
   /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
-  async doRunLibrarian(entityId, promptOverride) {
+  async doRunLibrarian(entityId, promptOverride, trigger = "call") {
     const events = await this.eventRepo.getRecent(entityId, 50);
     const currentFactsRows = await this.entryRepo.findRecentByEntityId(entityId, 100);
     const currentFacts = currentFactsRows.map((f) => {
@@ -2598,8 +2813,25 @@ var MaintenanceService = class {
     const facts = Array.isArray(result.facts) ? result.facts : [];
     const tasks = Array.isArray(result.tasks) ? result.tasks : [];
     const ontologyUpdates = result.ontology_updates;
-    const validFacts = facts.map(validateFact).filter((f) => f !== null);
-    const validTasks = tasks.map(validateTask).filter((t) => t !== null);
+    const diagBuffer = new DiagnosticBuffer();
+    const diagBase = { entityId, operation: "librarian", trigger };
+    const validFacts = [];
+    const validFactItemIndexes = [];
+    facts.forEach((raw, itemIndex) => {
+      const valid = validateFact(raw);
+      if (valid) {
+        validFacts.push(valid);
+        validFactItemIndexes.push(itemIndex);
+      } else {
+        diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { itemIndex, reason: factRejectionReason(raw) } });
+      }
+    });
+    const validTasks = [];
+    tasks.forEach((raw, itemIndex) => {
+      const valid = validateTask(raw);
+      if (valid) validTasks.push(valid);
+      else diagBuffer.push({ ...diagBase, code: "task_rejected", detail: { itemIndex, reason: taskRejectionReason(raw) } });
+    });
     const now = Date.now();
     const insertedFacts = [];
     await this.db.withTransactionAsync(async (tx) => {
@@ -2616,7 +2848,7 @@ var MaintenanceService = class {
       }
       const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
       const pendingEdges = [];
-      for (const fact of validFacts) {
+      for (const [k, fact] of validFacts.entries()) {
         const newTokens = titleTokens(fact.title);
         let skip = false;
         if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
@@ -2631,10 +2863,15 @@ var MaintenanceService = class {
             }
           }
         }
-        if (skip) continue;
+        if (skip) {
+          diagBuffer.push({ ...diagBase, code: "fact_deduplicated", detail: { itemIndex: validFactItemIndexes[k], reason: "fuzzy_title" } });
+          continue;
+        }
         const ontologyFact = fact;
-        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false }) ?? { okf_type: null, edges: [] };
         const id = generateId("fact_");
+        const validationDrops = [];
+        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false, drops: validationDrops }) ?? { okf_type: null, edges: [] };
+        for (const drop of validationDrops) diagBuffer.push(edgeDropDiagnostic(drop, { ...diagBase, factId: id }));
         const factObj = {
           id,
           entity_id: entityId,
@@ -2661,6 +2898,7 @@ var MaintenanceService = class {
         }
       }
       for (const item of pendingEdges) {
+        const resolveDrops = [];
         await this.ontologyService?.resolveAndPersistEdges(
           entityId,
           item.sourceId,
@@ -2669,8 +2907,10 @@ var MaintenanceService = class {
           manifest,
           titleIndex,
           tx,
-          now
+          now,
+          resolveDrops
         );
+        for (const drop of resolveDrops) diagBuffer.push(edgeDropDiagnostic(drop, diagBase));
       }
       for (const task of validTasks) {
         const id = generateId("task_");
@@ -2688,9 +2928,10 @@ var MaintenanceService = class {
         await this.taskRepo.upsert(taskObj, tx);
       }
     });
+    diagBuffer.flush(this.options);
     await this.searchService.sync(entityId);
     for (const fact of insertedFacts) {
-      await this.embeddingService.embedFact(fact);
+      await this.embeddingService.embedFact(fact, { operation: "librarian", trigger });
     }
     this.searchService.evictCache(entityId);
   }
@@ -2704,6 +2945,8 @@ var MaintenanceService = class {
   async doRunHeal(entityId, options) {
     const promptOverride = options?.promptOverride;
     const batchSize = options?.batchSize ?? HEAL_BATCH_SIZE;
+    const trigger = options?.trigger ?? "call";
+    const diagBase = { entityId, operation: "heal", trigger };
     if (!Number.isInteger(batchSize) || batchSize < 1) {
       throw new Error("Invalid batchSize: must be an integer >= 1");
     }
@@ -2739,6 +2982,7 @@ var MaintenanceService = class {
         await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
       } catch (hookErr) {
         console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal orphan pass for ${factId}:`, hookErr);
+        emitDiagnostic(this.options, { ...diagBase, code: "hook_failed", detail: { factId, reason: "on_embedding_persisted" } });
       }
     }
     const healCandidates = await this.entryRepo.findHealCandidatesByEntityId(entityId, batchSize, recheckCutoff);
@@ -2811,22 +3055,38 @@ var MaintenanceService = class {
     const safeDowngradedSet = /* @__PURE__ */ new Set();
     const safeDeletedSet = /* @__PURE__ */ new Set();
     const newFacts = [];
+    const newFactItemIndexes = [];
     for (const batchResult of outcome.results) {
       const mutableIds = new Set(batchResult.batch.map((f) => f.id));
       for (const id of batchResult.downgraded) if (mutableIds.has(id)) safeDowngradedSet.add(id);
       for (const id of batchResult.deleted) if (mutableIds.has(id)) safeDeletedSet.add(id);
-      newFacts.push(...batchResult.newFacts);
+      batchResult.newFacts.forEach((raw, itemIndex) => {
+        newFacts.push(raw);
+        newFactItemIndexes.push(itemIndex);
+      });
     }
     const safeDowngraded = Array.from(safeDowngradedSet);
     const safeDeleted = Array.from(safeDeletedSet);
-    const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
+    const diagBuffer = new DiagnosticBuffer();
+    const validNewFacts = [];
+    const validNewFactItemIndexes = [];
+    newFacts.forEach((raw, k) => {
+      const itemIndex = newFactItemIndexes[k];
+      const valid = validateFact(raw);
+      if (valid) {
+        validNewFacts.push(valid);
+        validNewFactItemIndexes.push(itemIndex);
+      } else {
+        diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { itemIndex, reason: factRejectionReason(raw) } });
+      }
+    });
     const insertedFacts = [];
     const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
     await this.db.withTransactionAsync(async (tx) => {
       await this.entryRepo.downgradeByIds(safeDowngraded, entityId, tx);
       await this.entryRepo.softDeleteByIds(safeDeleted, entityId, tx);
       const healFactsForDedupe = await this.entryRepo.findInferredTitlesByEntityId(entityId, tx);
-      for (const fact of validNewFacts) {
+      for (const [k, fact] of validNewFacts.entries()) {
         const newTokens = titleTokens(fact.title);
         let skip = false;
         if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
@@ -2840,7 +3100,10 @@ var MaintenanceService = class {
             }
           }
         }
-        if (skip) continue;
+        if (skip) {
+          diagBuffer.push({ ...diagBase, code: "fact_deduplicated", detail: { itemIndex: validNewFactItemIndexes[k], reason: "fuzzy_title" } });
+          continue;
+        }
         const id = generateId("fact_");
         const factObj = {
           id,
@@ -2875,16 +3138,21 @@ var MaintenanceService = class {
         tx
       );
     });
+    for (const { item, reason } of outcome.skipped) {
+      diagBuffer.push({ ...diagBase, code: "heal_skipped", detail: { factId: item.id, reason } });
+    }
+    diagBuffer.flush(this.options);
     await this.searchService.sync(entityId);
     for (const factId of uniqueDeletedFactIds) {
       try {
         await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
       } catch (hookErr) {
         console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal for ${factId}:`, hookErr);
+        emitDiagnostic(this.options, { ...diagBase, code: "hook_failed", detail: { factId, reason: "on_embedding_persisted" } });
       }
     }
     for (const fact of insertedFacts) {
-      await this.embeddingService.embedFact(fact);
+      await this.embeddingService.embedFact(fact, { operation: "heal", trigger });
     }
     this.searchService.evictCache(entityId);
     const skippedIds = new Set(outcome.skipped.map(({ item }) => item.id));
@@ -3024,6 +3292,8 @@ var MaintenanceService = class {
     let failedValidation = 0;
     let edgesAdded = 0;
     let abortedOntologyOff = false;
+    const diagBuffer = new DiagnosticBuffer();
+    const diagBase = { entityId, operation: "ontologyBackfill", trigger: "call" };
     await this.db.withTransactionAsync(async (tx) => {
       let { mode: txMode, manifest } = await ontologyService.getEffectiveState(entityId, tx);
       if (txMode === "off") {
@@ -3048,6 +3318,7 @@ var MaintenanceService = class {
           continue;
         }
         applied.add(fact.id);
+        const validationDrops = [];
         const normalized = ontologyService.validateAndNormalizeFact(
           {
             title: fact.title,
@@ -3058,8 +3329,11 @@ var MaintenanceService = class {
             edges: classification.edges
           },
           manifest,
-          { strict: false }
+          { strict: false, drops: validationDrops }
         );
+        for (const drop of validationDrops) {
+          diagBuffer.push(edgeDropDiagnostic(drop, { ...diagBase, factId: fact.id }));
+        }
         if (!normalized.okf_type) {
           failedValidation++;
           continue;
@@ -3073,7 +3347,8 @@ var MaintenanceService = class {
         }
       }
       for (const item of pendingEdges) {
-        edgesAdded += await ontologyService.resolveAndPersistEdges(
+        const resolveDrops = [];
+        const added = await ontologyService.resolveAndPersistEdges(
           entityId,
           item.sourceId,
           item.sourceType,
@@ -3081,11 +3356,17 @@ var MaintenanceService = class {
           manifest,
           titleIndex,
           tx,
-          now
+          now,
+          resolveDrops
         );
+        edgesAdded += added;
+        for (const drop of resolveDrops) {
+          diagBuffer.push(edgeDropDiagnostic(drop, diagBase));
+        }
       }
       await this.entryRepo.markOntologyChecked(batch.map((f) => f.id), entityId, now, tx);
     });
+    diagBuffer.flush(this.options);
     return { typed, failedValidation, edgesAdded, abortedOntologyOff };
   }
   _validatePruneDuration(value, name) {
@@ -4569,7 +4850,11 @@ var WriteService = class {
     if (shouldRunLibrarian) {
       try {
         this.jobManager.acquireLock("librarian", entityId);
-        this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint).catch(console.error).finally(() => {
+        const stage = { job: "librarian" };
+        this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint, stage).catch((err) => {
+          console.error(err);
+          this.reportBackgroundFailure(entityId, stage.job);
+        }).finally(() => {
           this.jobManager.releaseLock("librarian", entityId);
         });
       } catch (e) {
@@ -4577,17 +4862,21 @@ var WriteService = class {
         await this.metadataRepo.updateCheckpoint(entityId, { memory: prevMemoryCheckpoint }, this.db);
       }
     } else if (!this.jobManager.isBlocked("librarian", entityId)) {
-      this.maybeRunHeal(entityId, eventCount).catch(console.error);
+      this.maybeRunHeal(entityId, eventCount).catch((err) => {
+        console.error(err);
+        this.reportBackgroundFailure(entityId, "heal");
+      });
     }
   }
-  async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint) {
+  async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint, stage) {
     try {
-      await this.maintenanceService.doRunLibrarian(entityId);
+      await this.maintenanceService.doRunLibrarian(entityId, void 0, "auto");
       await this.metadataRepo.updateCheckpoint(entityId, { memory: currentEventCount }, this.db);
     } catch (e) {
       await this.metadataRepo.updateCheckpoint(entityId, { memory: prevCheckpoint }, this.db);
       throw e;
     }
+    stage.job = "heal";
     await this.maybeRunHeal(entityId, currentEventCount);
   }
   /**
@@ -4603,7 +4892,7 @@ var WriteService = class {
     const shouldRunHeal = currentEventCount - healCheckpoint >= autoHealThreshold;
     if (shouldRunHeal && this.jobManager.tryAcquireAutoHealLock(entityId)) {
       try {
-        const result = await this.maintenanceService.doRunHeal(entityId);
+        const result = await this.maintenanceService.doRunHeal(entityId, { trigger: "auto" });
         if (result.remaining === 0) {
           await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
         }
@@ -4612,6 +4901,15 @@ var WriteService = class {
       }
     }
   }
+  reportBackgroundFailure(entityId, job) {
+    emitDiagnostic(this.options, {
+      code: "background_job_failed",
+      operation: job,
+      trigger: "auto",
+      entityId,
+      detail: { reason: "unhandled_rejection" }
+    });
+  }
 };
 
 exports.EmbeddingService = EmbeddingService;