@equationalapplications/core-llm-wiki 7.2.0 → 7.3.0

package/dist/index.js

@@ -2768,20 +2768,27 @@ function mergeOntologyUpdates(current, updates) {
 function validateInlineEdges(sourceType, _targetType, edges, manifest, opts) {
   const strict = opts?.strict === true;
   const entityId = opts?.entityId ?? "";
+  const drops = opts?.drops;
+  const drop = (reason, edgeType) => {
+    drops?.push({ reason, sourceId: null, edgeType, sourceNodeType: sourceType, targetNodeType: null });
+  };
   if (!Array.isArray(edges)) {
     if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", "");
+    drop("invalid_shape", null);
     return [];
   }
   const valid = [];
   for (const edge of edges) {
     if (typeof edge?.edge_type !== "string" || typeof edge?.target_title !== "string") {
       if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", String(edge?.edge_type ?? ""));
+      drop("invalid_shape", typeof edge?.edge_type === "string" ? edge.edge_type : null);
       continue;
     }
     const defs = resolveEdgeDefinitions(edge.edge_type, manifest);
     const match = defs.find((d) => typeSatisfies(d.source_type, sourceType, manifest));
     if (!match) {
       if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", edge.edge_type);
+      drop("type_not_in_manifest", edge.edge_type);
       continue;
     }
     valid.push({ edge_type: match.type, target_title: edge.target_title });
@@ -4129,6 +4136,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);
@@ -4148,6 +4166,104 @@ function jaccardScore(a, b) {
   return intersection.size / union.size;
 }
 
+// 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/prompts.ts
 var LIBRARIAN_SYSTEM_PROMPT = `You are a knowledge extraction agent. Your job is to analyze recent episodic events and extract stable facts and actionable tasks about the user or entity.
 Return ONLY a valid JSON object matching this schema:
@@ -4435,9 +4551,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) {
@@ -4482,23 +4613,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,
@@ -4511,7 +4667,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);
@@ -4519,7 +4675,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);
         }
@@ -4533,6 +4689,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));
@@ -4541,11 +4698,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 = {
@@ -4691,6 +4855,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({
@@ -4731,7 +4908,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));
@@ -4756,8 +4933,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 ?? "",
@@ -4782,6 +4963,7 @@ var IngestionService = class {
     }
     const hostEdges = [];
     for (const req of rawEdgeRequests) {
+      const resolveDrops = [];
       const resolved = this.ontologyService?.resolveEdges(
         entityId,
         req.sourceId,
@@ -4789,8 +4971,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 });
       }
@@ -4799,7 +4985,7 @@ var IngestionService = class {
       entityId,
       { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
       tx,
-      { strict: false }
+      { strict: false, diag: { buffer: diagBuffer, operation: "ingest" } }
     );
     return { deletedSourceFactIds, insertedFacts };
   }
@@ -4823,7 +5009,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)));
@@ -4834,6 +5020,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;
       }
@@ -5234,7 +5427,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++;
         }
@@ -5355,7 +5548,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) => {
@@ -5377,8 +5570,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) => {
@@ -5395,7 +5605,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) {
@@ -5410,10 +5620,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,
@@ -5440,6 +5655,7 @@ var MaintenanceService = class {
         }
       }
       for (const item of pendingEdges) {
+        const resolveDrops = [];
         await this.ontologyService?.resolveAndPersistEdges(
           entityId,
           item.sourceId,
@@ -5448,8 +5664,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_");
@@ -5467,9 +5685,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);
   }
@@ -5483,6 +5702,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");
     }
@@ -5518,6 +5739,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);
@@ -5590,22 +5812,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) {
@@ -5619,7 +5857,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,
@@ -5654,16 +5895,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));
@@ -5803,6 +6049,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") {
@@ -5827,6 +6075,7 @@ var MaintenanceService = class {
           continue;
         }
         applied.add(fact.id);
+        const validationDrops = [];
         const normalized = ontologyService.validateAndNormalizeFact(
           {
             title: fact.title,
@@ -5837,8 +6086,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;
@@ -5852,7 +6104,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,
@@ -5860,11 +6113,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) {
@@ -6266,7 +6525,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);
         }
@@ -6291,6 +6550,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
+          );
         }
       }
     }
@@ -6307,6 +6571,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
+          );
         }
       }
     }
@@ -6469,7 +6738,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;
@@ -6491,6 +6760,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" };
       }
@@ -6504,11 +6774,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" };
     }
@@ -6518,15 +6790,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 {
@@ -6540,8 +6828,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) {
@@ -7341,7 +7629,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) {
@@ -7349,17 +7641,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);
   }
   /**
@@ -7375,7 +7671,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);
         }
@@ -7384,6 +7680,15 @@ var WriteService = class {
       }
     }
   }
+  reportBackgroundFailure(entityId, job) {
+    emitDiagnostic(this.options, {
+      code: "background_job_failed",
+      operation: job,
+      trigger: "auto",
+      entityId,
+      detail: { reason: "unhandled_rejection" }
+    });
+  }
 };
 
 // src/prompts/ontology.ts
@@ -7472,6 +7777,17 @@ var OntologyService = class {
     const canonical = resolveNodeType(rawType, manifest);
     if (!canonical) {
       if (strict) throw new WikiStrictOntologyViolation(opts?.entityId ?? "", "node", rawType);
+      if (opts?.drops && Array.isArray(fact.edges)) {
+        for (const edge of fact.edges) {
+          opts.drops.push({
+            reason: "no_source_type",
+            sourceId: null,
+            edgeType: typeof edge?.edge_type === "string" ? edge.edge_type : null,
+            sourceNodeType: null,
+            targetNodeType: null
+          });
+        }
+      }
       return { okf_type: null, edges: [] };
     }
     const edges = validateInlineEdges(canonical, null, fact.edges ?? [], manifest, opts);
@@ -7484,18 +7800,39 @@ var OntologyService = class {
    * writes inside their own transaction (e.g. `IngestionService.ingestDocument`
    * when delegating to `upsertGraphCore`).
    */
-  resolveEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, now) {
-    if (!sourceType || edges.length === 0) return [];
+  resolveEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, now, drops) {
+    if (edges.length === 0) return [];
+    if (!sourceType) {
+      for (const edge of edges) {
+        drops?.push({ reason: "no_source_type", sourceId, edgeType: edge.edge_type, sourceNodeType: null, targetNodeType: null });
+      }
+      return [];
+    }
     const out = [];
     for (const edge of edges) {
       const candidates = resolveEdgeDefinitions(edge.edge_type, manifest).filter((d) => typeSatisfies(d.source_type, sourceType, manifest));
-      if (candidates.length === 0) continue;
+      if (candidates.length === 0) {
+        drops?.push({ reason: "type_not_in_manifest", sourceId, edgeType: edge.edge_type, sourceNodeType: sourceType, targetNodeType: null });
+        continue;
+      }
       const targetKey = normalizeTitleKey(edge.target_title);
       const target = titleIndex.get(targetKey);
-      if (!target) continue;
+      if (!target) {
+        drops?.push({ reason: "target_not_found", sourceId, edgeType: edge.edge_type, sourceNodeType: sourceType, targetNodeType: null });
+        continue;
+      }
       const targetType = (target.okf_type ?? "").trim().toLowerCase();
       const def = candidates.find((d) => d.target_type.trim().toLowerCase() === targetType) ?? candidates.find((d) => typeSatisfies(d.target_type, targetType, manifest));
-      if (!def) continue;
+      if (!def) {
+        drops?.push({
+          reason: "target_type_mismatch",
+          sourceId,
+          edgeType: edge.edge_type,
+          sourceNodeType: sourceType,
+          targetNodeType: target.okf_type ?? null
+        });
+        continue;
+      }
       out.push({
         id: generateId(),
         entity_id: entityId,
@@ -7514,8 +7851,8 @@ var OntologyService = class {
    * want self-contained edge persistence (e.g. MaintenanceService heal /
    * backfill callers that do not have a separate edge-write step).
    */
-  async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now) {
-    const resolved = this.resolveEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, now);
+  async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now, drops) {
+    const resolved = this.resolveEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, now, drops);
     let persisted = 0;
     for (const edge of resolved) {
       const inserted = await this.edgeRepo.addIgnoreDuplicate(edge, tx);
@@ -8136,11 +8473,15 @@ var WikiMemory = class {
         attemptedSourceRef: sourceRef
       });
     }
-    return this.ingestionService.upsertGraphCore(
+    const diagBuffer = new DiagnosticBuffer();
+    const result = await this.ingestionService.upsertGraphCore(
       entityId,
       { sourceRef, sourceHash, nodes: params.nodes, edges: params.edges },
-      adapter
+      adapter,
+      { diag: { buffer: diagBuffer, operation: "upsertGraph" } }
     );
+    diagBuffer.flush(this.options);
+    return result;
   }
   /**
    * Returns up to `limit` unprocessed outbox events, oldest first.