@equationalapplications/core-llm-wiki 7.2.1 → 7.4.0

package/dist/{chunk-TTECJ3S3.mjs → chunk-G5OR2VWD.mjs}

@@ -168,6 +168,14 @@ var WikiInvalidReadOptions = class _WikiInvalidReadOptions extends Error {
     Object.setPrototypeOf(this, _WikiInvalidReadOptions.prototype);
   }
 };
+var WikiDraftNotFound = class _WikiDraftNotFound extends Error {
+  constructor() {
+    super("No draft fact with that id exists for this entity.");
+    this.code = "WIKI_DRAFT_NOT_FOUND";
+    this.name = "WikiDraftNotFound";
+    Object.setPrototypeOf(this, _WikiDraftNotFound.prototype);
+  }
+};
 
 // src/utils/ids.ts
 var _injectedGetRandomValues = null;
@@ -336,20 +344,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 });
@@ -1526,6 +1541,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);
@@ -1765,6 +1791,104 @@ function applyBodyTruncation(candidates, attemptLevel, bodyTruncationChars) {
 var DEFAULT_MAX_CHUNK_LENGTH = 12e3;
 var DEFAULT_CHUNK_OVERLAP = 400;
 
+// 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/IngestionService.ts
 function zeroChunkResult(duplicateOf) {
   const result = {
@@ -1832,9 +1956,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) {
@@ -1879,23 +2018,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,
@@ -1908,7 +2072,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);
@@ -1916,7 +2080,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);
         }
@@ -1930,6 +2094,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));
@@ -1938,11 +2103,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 = {
@@ -2088,6 +2260,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({
@@ -2128,7 +2313,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));
@@ -2153,8 +2338,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 ?? "",
@@ -2179,6 +2368,7 @@ var IngestionService = class {
     }
     const hostEdges = [];
     for (const req of rawEdgeRequests) {
+      const resolveDrops = [];
       const resolved = this.ontologyService?.resolveEdges(
         entityId,
         req.sourceId,
@@ -2186,8 +2376,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 });
       }
@@ -2196,7 +2390,7 @@ var IngestionService = class {
       entityId,
       { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
       tx,
-      { strict: false }
+      { strict: false, diag: { buffer: diagBuffer, operation: "ingest" } }
     );
     return { deletedSourceFactIds, insertedFacts };
   }
@@ -2220,7 +2414,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)));
@@ -2231,6 +2425,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;
       }
@@ -2817,7 +3018,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++;
         }
@@ -2938,7 +3139,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) => {
@@ -2960,8 +3161,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) => {
@@ -2978,7 +3196,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) {
@@ -2993,10 +3211,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,
@@ -3023,6 +3246,7 @@ var MaintenanceService = class {
         }
       }
       for (const item of pendingEdges) {
+        const resolveDrops = [];
         await this.ontologyService?.resolveAndPersistEdges(
           entityId,
           item.sourceId,
@@ -3031,8 +3255,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_");
@@ -3050,9 +3276,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);
   }
@@ -3066,6 +3293,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");
     }
@@ -3101,6 +3330,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);
@@ -3173,22 +3403,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) {
@@ -3202,7 +3448,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,
@@ -3237,16 +3486,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));
@@ -3386,6 +3640,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") {
@@ -3410,6 +3666,7 @@ var MaintenanceService = class {
           continue;
         }
         applied.add(fact.id);
+        const validationDrops = [];
         const normalized = ontologyService.validateAndNormalizeFact(
           {
             title: fact.title,
@@ -3420,8 +3677,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;
@@ -3435,7 +3695,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,
@@ -3443,11 +3704,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) {
@@ -3849,7 +4116,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);
         }
@@ -3874,6 +4141,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
+          );
         }
       }
     }
@@ -3890,6 +4162,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
+          );
         }
       }
     }
@@ -4052,7 +4329,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;
@@ -4074,6 +4351,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" };
       }
@@ -4087,11 +4365,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" };
     }
@@ -4101,15 +4381,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 {
@@ -4123,8 +4419,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) {
@@ -4264,6 +4560,7 @@ function selectWithFloors(sortedRows, floors, maxResults) {
 }
 
 // src/services/RetrievalService.ts
+var EMPTY_ID_SET = /* @__PURE__ */ new Set();
 var RetrievalService = class {
   constructor(options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService) {
     this.options = options;
@@ -4296,6 +4593,7 @@ var RetrievalService = class {
     }
     const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
     const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
+    const excludeDrafts = (options?.excludeDrafts ?? config?.excludeDrafts ?? false) === true;
     const trimmedQuery = query.trim();
     const sanitizedTierFloors = trimmedQuery && exposeMetadata ? validateTierFloors(
       entityIds,
@@ -4315,6 +4613,9 @@ var RetrievalService = class {
     if (maxResults === 0) ; else if (trimmedQuery) {
       let usedEmbed = false;
       const scoredEntityIds = this._filterScoredEntities(entityIds, sanitizedTierWeights, options?.includeZeroWeightEntities);
+      const draftIds = excludeDrafts && scoredEntityIds.length > 0 ? await this.entryRepo.findDraftIdsByEntityIds(scoredEntityIds) : EMPTY_ID_SET;
+      const draftPad = draftIds.size;
+      const padLimit = (n) => n >= Number.MAX_SAFE_INTEGER ? n : n + draftPad;
       if (scoredEntityIds.length === 0) {
         usedEmbed = true;
       } else if (!skipEmbed && embedFn) {
@@ -4348,7 +4649,7 @@ var RetrievalService = class {
           let miniSearchScores;
           if (effectivePreFilterLimit !== void 0) {
             populateCache = false;
-            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER);
+            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER).filter((r) => !draftIds.has(r.id));
             if (preResults.length === 0) {
               candidateRows = null;
             } else {
@@ -4370,9 +4671,9 @@ var RetrievalService = class {
             }
           } else {
             if (useRanker) {
-              candidateRows = await this.entryRepo.findMetadataByEntityIds(scoredEntityIds);
+              candidateRows = this._withoutDrafts(await this.entryRepo.findMetadataByEntityIds(scoredEntityIds), draftIds);
             } else {
-              candidateRows = await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds);
+              candidateRows = this._withoutDrafts(await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds), draftIds);
             }
             if (weight !== void 0 && weight < 1) {
               miniSearchScores = this.searchService.getMiniSearchScores(trimmedQuery, scoredEntityIds);
@@ -4402,7 +4703,7 @@ var RetrievalService = class {
                       candidateRows: rowsForEntity,
                       weight,
                       miniSearchScores,
-                      limit: Math.max(maxResults * 2, maxResults + 50)
+                      limit: padLimit(Math.max(maxResults * 2, maxResults + 50))
                     });
                     return ranked.map((row) => ({ ...row, entity_id: scopedEntityId }));
                   })
@@ -4616,7 +4917,7 @@ var RetrievalService = class {
                   });
                 } else if (policy === "keyword") {
                   const hasActiveFloorsKeywordFallback = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
-                  const keywordOversampledLimit = hasActiveFloorsKeywordFallback ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
+                  const keywordOversampledLimit = hasActiveFloorsKeywordFallback ? Number.MAX_SAFE_INTEGER : padLimit(Math.max(maxResults * 2, maxResults + 50));
                   const preFilteredIds = effectivePreFilterLimit !== void 0 ? new Set(candidateRows.map((r) => r.id)) : void 0;
                   const keywordResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, keywordOversampledLimit);
                   const topResults = preFilteredIds === void 0 ? keywordResults : keywordResults.filter((r) => preFilteredIds.has(r.id));
@@ -4657,6 +4958,7 @@ var RetrievalService = class {
                 // read() re-sorts after applying tier weights
               });
             }
+            if (draftPad > 0) scored = scored.filter((s) => !draftIds.has(s.id));
             if (scored.length > 0) {
               scored = scored.map((row) => ({
                 ...row,
@@ -4719,8 +5021,8 @@ var RetrievalService = class {
       }
       if (!usedEmbed && scoredEntityIds.length > 0) {
         const hasActiveFloors = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
-        const fallbackOversampledLimit = hasActiveFloors ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
-        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit);
+        const fallbackOversampledLimit = hasActiveFloors ? Number.MAX_SAFE_INTEGER : padLimit(Math.max(maxResults * 2, maxResults + 50));
+        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit).filter((r) => !draftIds.has(r.id));
         const candidates = results.map((r) => ({
           id: r.id,
           entity_id: r.entity_id,
@@ -4744,7 +5046,7 @@ var RetrievalService = class {
         await this.entryRepo.trackAccess(ids, now);
       }
     } else {
-      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
+      facts = excludeDrafts ? await this.entryRepo.findRecentByEntityIds(entityIds, maxResults, void 0, { excludeDrafts: true }) : await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
     }
     const eventsLimit = Math.min(10 * entityIds.length, 100);
     const [tasks, events] = await Promise.all([
@@ -4780,6 +5082,9 @@ var RetrievalService = class {
   _tieBreakSort(items) {
     items.sort((a, b) => this._compareScoredRows(a, b));
   }
+  _withoutDrafts(rows, draftIds) {
+    return draftIds.size === 0 ? rows : rows.filter((row) => !draftIds.has(row.id));
+  }
   /**
    * Comparator for score + deterministic tie-break fields.
    * Negative return means "a ranks ahead of b" for descending score order.
@@ -4924,7 +5229,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) {
@@ -4932,17 +5241,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);
   }
   /**
@@ -4958,7 +5271,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);
         }
@@ -4967,8 +5280,17 @@ var WriteService = class {
       }
     }
   }
+  reportBackgroundFailure(entityId, job) {
+    emitDiagnostic(this.options, {
+      code: "background_job_failed",
+      operation: job,
+      trigger: "auto",
+      entityId,
+      detail: { reason: "unhandled_rejection" }
+    });
+  }
 };
 
-export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-TTECJ3S3.mjs.map
-//# sourceMappingURL=chunk-TTECJ3S3.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-G5OR2VWD.mjs.map
+//# sourceMappingURL=chunk-G5OR2VWD.mjs.map