@equationalapplications/core-llm-wiki 7.2.1 → 7.4.0

package/dist/index.js

@@ -333,6 +333,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/db/serializedAdapter.ts
 function isDriverError(err) {
@@ -1757,16 +1765,52 @@ var EntryRepository = class extends BaseRepository {
       `UPDATE ${this.prefix}entries SET source_type = 'librarian_inferred' WHERE source_type = 'agent_inferred';`
     ].join("\n");
   }
-  async findRecentByEntityIds(entityIds, limit, tx) {
+  async findRecentByEntityIds(entityIds, limit, tx, opts) {
     if (entityIds.length === 0) return [];
     const executor = this.getExecutor(tx);
     const placeholders = entityIds.map(() => "?").join(",");
+    const draftClause = opts?.excludeDrafts === true ? ` AND lifecycle_status != 'draft'` : "";
     const rows = await executor.getAllAsync(
-      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT ?`,
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL${draftClause} ORDER BY updated_at DESC LIMIT ?`,
       [...entityIds, limit]
     );
     return rows.map(mapRowToFact);
   }
+  /** IDs of live draft facts for the given entities (spec §5.1). Callers pass ≤ 100 entity ids. */
+  async findDraftIdsByEntityIds(entityIds, tx) {
+    if (entityIds.length === 0) return /* @__PURE__ */ new Set();
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    const rows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL AND lifecycle_status = 'draft'`,
+      [...entityIds]
+    );
+    return new Set(rows.map((r) => r.id));
+  }
+  /** Live drafts for one entity, newest first, keyset-paged by (created_at, id). */
+  async listDraftsByEntityId(entityId, limit, after, tx) {
+    const executor = this.getExecutor(tx);
+    const afterClause = after ? ` AND (created_at < ? OR (created_at = ? AND id < ?))` : "";
+    const args = after ? [entityId, after.createdAt, after.createdAt, after.id, limit] : [entityId, limit];
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND lifecycle_status = 'draft'${afterClause}
+       ORDER BY created_at DESC, id DESC LIMIT ?`,
+      args
+    );
+    return rows.map(mapRowToFact);
+  }
+  /** True iff `entryId` is a live draft owned by `entityId`. */
+  async isLiveDraft(entryId, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE id = ? AND entity_id = ? AND deleted_at IS NULL AND lifecycle_status = 'draft'`,
+      [entryId, entityId]
+    );
+    return row != null;
+  }
   /**
    * Live untyped facts eligible for ontology backfill, oldest first.
    * Skips facts checked within the recheck cooldown (ontology_checked_at > recheckCutoff).
@@ -2577,6 +2621,7 @@ var EdgeRepository = class extends BaseRepository {
             END
           ) >= ?
           AND n.source_type NOT IN (${excludeSourceTypesPlaceholders})
+          AND (? = 0 OR n.lifecycle_status != 'draft')
         WHERE w.depth < ?
           AND instr(w.visited, ',' || (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END) || ',') = 0
       )
@@ -2596,6 +2641,7 @@ var EdgeRepository = class extends BaseRepository {
       entityId,
       minConfidenceRank,
       ...opts.excludeSourceTypes,
+      opts.excludeDrafts === true ? 1 : 0,
       opts.maxDepth,
       opts.maxNodes
     ];
@@ -2768,20 +2814,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 +4182,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 +4212,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 +4597,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 +4659,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 +4713,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 +4721,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 +4735,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 +4744,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 +4901,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 +4954,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 +4979,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 +5009,7 @@ var IngestionService = class {
     }
     const hostEdges = [];
     for (const req of rawEdgeRequests) {
+      const resolveDrops = [];
       const resolved = this.ontologyService?.resolveEdges(
         entityId,
         req.sourceId,
@@ -4789,8 +5017,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 +5031,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 +5055,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 +5066,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 +5473,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 +5594,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 +5616,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 +5651,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 +5666,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 +5701,7 @@ var MaintenanceService = class {
         }
       }
       for (const item of pendingEdges) {
+        const resolveDrops = [];
         await this.ontologyService?.resolveAndPersistEdges(
           entityId,
           item.sourceId,
@@ -5448,8 +5710,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 +5731,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 +5748,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 +5785,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 +5858,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 +5903,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 +5941,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 +6095,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 +6121,7 @@ var MaintenanceService = class {
           continue;
         }
         applied.add(fact.id);
+        const validationDrops = [];
         const normalized = ontologyService.validateAndNormalizeFact(
           {
             title: fact.title,
@@ -5837,8 +6132,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 +6150,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 +6159,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 +6571,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 +6596,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 +6617,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 +6784,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 +6806,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 +6820,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 +6836,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 +6874,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) {
@@ -6681,6 +7015,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;
@@ -6713,6 +7048,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,
@@ -6732,6 +7068,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) {
@@ -6765,7 +7104,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 {
@@ -6787,9 +7126,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);
@@ -6819,7 +7158,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 }));
                   })
@@ -7033,7 +7372,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));
@@ -7074,6 +7413,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,
@@ -7136,8 +7476,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,
@@ -7161,7 +7501,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([
@@ -7197,6 +7537,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.
@@ -7341,7 +7684,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 +7696,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 +7726,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 +7735,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 +7832,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 +7855,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 +7906,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);
@@ -7544,6 +7936,7 @@ var GraphTraversalService = class {
       edgeTypes: options.edgeTypes,
       minConfidence: options.minTraversalConfidence ?? this.config.minTraversalConfidence ?? "tentative",
       excludeSourceTypes: options.excludeSourceTypes ?? this.config.excludeSourceTypes ?? [],
+      excludeDrafts: options.excludeDrafts ?? this.config.excludeDrafts ?? false,
       maxNodes
     };
     const { nodeIds, edges } = await this.edgeRepo.getNeighborhood(entityId, options.sourceId, opts);
@@ -7717,6 +8110,15 @@ var OkfTrustWritesRepository = class {
 
 // src/WikiMemory.ts
 var TABLE_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,30}_$/;
+function decodeDraftCursor(cursor) {
+  const sep = typeof cursor === "string" ? cursor.indexOf(":") : -1;
+  const createdAt = sep > 0 ? Number(cursor.slice(0, sep)) : Number.NaN;
+  const id = sep > 0 ? cursor.slice(sep + 1) : "";
+  if (!Number.isSafeInteger(createdAt) || id.length === 0) {
+    throw new TypeError("Invalid listDrafts cursor.");
+  }
+  return { createdAt, id };
+}
 var _testAccessNonTestEnvWarned;
 var WikiMemory = class {
   constructor(db, options) {
@@ -8136,11 +8538,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.
@@ -8257,6 +8663,43 @@ var WikiMemory = class {
   async setLifecycleStatus(entryId, entityId, status) {
     return this.okfTrustWrites.setLifecycleStatus(entryId, entityId, status);
   }
+  /**
+   * Live draft facts for one entity, newest first (spec §5.2). Default page
+   * size 50, clamped to [1, 500]. Pass `nextCursor` back unchanged for the next page.
+   */
+  async listDrafts(entityId, options) {
+    const rawLimit = options?.limit;
+    const limit = typeof rawLimit === "number" && Number.isFinite(rawLimit) ? Math.min(500, Math.max(1, Math.floor(rawLimit))) : 50;
+    const after = options?.cursor === void 0 ? null : decodeDraftCursor(options.cursor);
+    const rows = await this.entryRepo.listDraftsByEntityId(entityId, limit + 1, after);
+    const facts = rows.slice(0, limit);
+    const last = facts[facts.length - 1];
+    return {
+      facts,
+      nextCursor: rows.length > limit && last ? `${last.created_at}:${last.id}` : null
+    };
+  }
+  /**
+   * Promote a draft to `stable` and record who reviewed it, atomically
+   * (spec §5.2). Metadata writes only: `updated_at` is not bumped and no
+   * outbox event is pushed. Pass `by: 'human:<id>'` so `trustTier` becomes
+   * `'human-reviewed'`.
+   *
+   * @throws WikiDraftNotFound when no live draft with that id exists for the entity.
+   */
+  async promoteDraft(entryId, entityId, reviewer) {
+    const by = reviewer?.by;
+    if (typeof by !== "string" || by.trim().length === 0) {
+      throw new TypeError("promoteDraft requires reviewer.by to be a non-empty string.");
+    }
+    await this.db.withTransactionAsync(async (tx) => {
+      if (!await this.entryRepo.isLiveDraft(entryId, entityId, tx)) {
+        throw new WikiDraftNotFound();
+      }
+      await this.okfTrustWrites.setLifecycleStatus(entryId, entityId, "stable", tx);
+      await this.okfTrustWrites.writeOkfTrust(entryId, entityId, [{ by, at: (/* @__PURE__ */ new Date()).toISOString() }], tx);
+    });
+  }
   /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
   async setStaleAfter(entryId, entityId, date) {
     return this.okfTrustWrites.setStaleAfter(entryId, entityId, date);
@@ -9208,6 +9651,7 @@ exports.ONTOLOGY_BACKFILL_SYSTEM_PROMPT = ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
 exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
+exports.WikiDraftNotFound = WikiDraftNotFound;
 exports.WikiDuplicateHashError = WikiDuplicateHashError;
 exports.WikiGraphNodeOwnershipConflict = WikiGraphNodeOwnershipConflict;
 exports.WikiIngestEmptyError = WikiIngestEmptyError;