@equationalapplications/core-llm-wiki 5.3.1 → 5.5.0

package/dist/testing.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var coreOkf = require('@equationalapplications/core-okf');
 var MiniSearch = require('minisearch');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -109,26 +110,88 @@ var PrunePartialFailureError = class extends Error {
   }
 };
 var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
+var WikiParseError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = "WikiParseError";
+    this.tier = opts.tier;
+    this.position = opts.position ?? null;
+    this.slice = opts.slice ?? "";
+  }
+};
+var WikiIngestEmptyError = class extends Error {
+  constructor(params) {
+    const summary = `All ${params.chunks} chunks failed for sourceRef "${params.sourceRef}"; see parseFailures for per-chunk detail`;
+    super(summary);
+    this.name = "WikiIngestEmptyError";
+    this.parseFailures = params.parseFailures;
+    this.sourceRef = params.sourceRef;
+    this.chunks = params.chunks;
+  }
+};
 
 // src/utils/pure.ts
+var MAX_REPAIR_CANDIDATES = 5;
+function throwNoJsonFound(text, start) {
+  throw new WikiParseError(
+    "No JSON object/array found in LLM response",
+    { tier: "strict", position: start, slice: text }
+  );
+}
 function parseJsonResponse(text) {
   const firstBrace = text.indexOf("{");
   const firstBracket = text.indexOf("[");
   let start;
   let openChar;
-  let closeChar;
   const useBrace = firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket);
   if (useBrace) {
     start = firstBrace;
     openChar = "{";
-    closeChar = "}";
   } else if (firstBracket !== -1) {
     start = firstBracket;
     openChar = "[";
-    closeChar = "]";
   } else {
-    throw new SyntaxError("No JSON object/array found in LLM response");
+    throwNoJsonFound(text, null);
+  }
+  const slice = scanJsonSlice(text, start, openChar);
+  if (slice !== null) {
+    try {
+      return JSON.parse(slice);
+    } catch {
+    }
   }
+  const repairOdd = containerAwareRepair(text, start, false);
+  if (repairOdd.success !== null && !repairOdd.ambiguous) {
+    return repairOdd.success;
+  }
+  const repairEven = containerAwareRepair(text, start, true);
+  if (repairOdd.success !== null && repairEven.success !== null) {
+    const pick = repairEven.escapes < repairOdd.escapes ? repairEven : repairOdd;
+    return pick.success;
+  }
+  if (repairOdd.success !== null) {
+    return repairOdd.success;
+  }
+  if (repairEven.success !== null) {
+    return repairEven.success;
+  }
+  const repair = repairEven.failed !== null ? repairEven : repairOdd;
+  if (repair.failed !== null) {
+    throw new WikiParseError(
+      `Repair produced a candidate but JSON.parse rejected it: ${repair.failed.message}`,
+      { tier: "repair", position: repair.failed.position, slice: repair.failed.candidate }
+    );
+  }
+  if (slice === null) {
+    throwNoJsonFound(text, start);
+  }
+  throw new WikiParseError(
+    "No parsable JSON candidate found",
+    { tier: "all", position: start, slice: text }
+  );
+}
+function scanJsonSlice(text, start, openChar) {
+  const closeChar = openChar === "{" ? "}" : "]";
   let depth = 0;
   let inString = false;
   let escape = false;
@@ -160,8 +223,193 @@ function parseJsonResponse(text) {
       }
     }
   }
-  if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
-  return JSON.parse(text.slice(start, end + 1));
+  if (end === -1) return null;
+  return safeSlice(text, start, end + 1);
+}
+function containerAwareRepair(text, start, closeOnEvenParity) {
+  const stack = [];
+  let inString = false;
+  let stringRole = null;
+  let escape = false;
+  let i = start;
+  let out = "";
+  let bareQuoteCount = 0;
+  let bestFailed = null;
+  let escapes = 0;
+  let ambiguous = false;
+  let bestSuccess = null;
+  let attempts = 0;
+  function tryEmitCandidate(candidate) {
+    attempts++;
+    try {
+      bestSuccess = JSON.parse(candidate);
+      return true;
+    } catch (err) {
+      if (bestFailed === null) {
+        bestFailed = {
+          candidate,
+          position: extractParsePosition(err),
+          message: safeErrorToString(err)
+        };
+      }
+      return false;
+    }
+  }
+  while (i < text.length) {
+    const ch = text[i];
+    if (stack.length === 0 && !inString) {
+      if (ch === "{" || ch === "[") {
+        stack.push({ container: ch === "{" ? "object" : "array", expectKey: true });
+        out += ch;
+      }
+      i++;
+      continue;
+    }
+    if (escape) {
+      out += ch;
+      escape = false;
+      i++;
+      continue;
+    }
+    if (inString && ch === "\\") {
+      out += ch;
+      escape = true;
+      i++;
+      continue;
+    }
+    if (inString) {
+      const code = ch.charCodeAt(0);
+      if (code < 32) {
+        out += controlCharEscape(code);
+        i++;
+        continue;
+      }
+    }
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && (text[j] === " " || text[j] === "	" || text[j] === "\n" || text[j] === "\r")) {
+        j++;
+      }
+      const next = j < text.length ? text[j] : "";
+      if (!inString) {
+        if (next === "}" || next === "]") {
+          if (j > i + 1) out += text.slice(i + 1, j);
+          out += next;
+          i = j + 1;
+          stack.pop();
+          if (stack.length === 0) {
+            if (tryEmitCandidate(out)) return { success: bestSuccess, failed: bestFailed, escapes, ambiguous };
+            if (attempts >= MAX_REPAIR_CANDIDATES) break;
+            out = "";
+          }
+          continue;
+        }
+        const top = stack[stack.length - 1];
+        stringRole = top?.container === "object" && top.expectKey ? "key" : "value";
+        out += ch;
+        inString = true;
+        i++;
+        continue;
+      }
+      const commaOnly = next === ",";
+      const isKeyClose = stringRole === "key" && (next === ":" || next === '"' && j + 1 < text.length && text[j + 1] === ":");
+      const isValueClose = !commaOnly && (next === "," || next === "}" || next === "]");
+      if (commaOnly && bareQuoteCount > 0) ambiguous = true;
+      const shouldCommaClose = commaOnly && (bareQuoteCount === 0 || (closeOnEvenParity ? bareQuoteCount % 2 === 0 : bareQuoteCount % 2 === 1));
+      const isClosing = isKeyClose || isValueClose || shouldCommaClose;
+      if (isClosing) {
+        out += ch;
+        inString = false;
+        const topFrame = stack[stack.length - 1];
+        if (topFrame && topFrame.container === "object") {
+          topFrame.expectKey = stringRole === "value";
+        }
+        stringRole = null;
+        bareQuoteCount = 0;
+        i++;
+        continue;
+      }
+      out += "\\" + ch;
+      bareQuoteCount++;
+      escapes++;
+      i++;
+      continue;
+    }
+    if (!inString && (ch === "{" || ch === "[")) {
+      stack.push({ container: ch === "{" ? "object" : "array", expectKey: true });
+      out += ch;
+      i++;
+      continue;
+    }
+    if (!inString && ch === ",") {
+      const topFrame = stack[stack.length - 1];
+      if (topFrame && topFrame.container === "object") {
+        topFrame.expectKey = true;
+      }
+      out += ch;
+      i++;
+      continue;
+    }
+    if (!inString && (ch === "}" || ch === "]")) {
+      out += ch;
+      stack.pop();
+      if (stack.length === 0) {
+        if (tryEmitCandidate(out)) return { success: bestSuccess, failed: bestFailed, escapes, ambiguous };
+        if (attempts >= MAX_REPAIR_CANDIDATES) break;
+        out = "";
+      }
+      i++;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return { success: null, failed: bestFailed, escapes, ambiguous };
+}
+function controlCharEscape(code) {
+  switch (code) {
+    case 10:
+      return "\\n";
+    case 9:
+      return "\\t";
+    case 13:
+      return "\\r";
+    case 8:
+      return "\\b";
+    case 12:
+      return "\\f";
+    default:
+      return "\\u" + code.toString(16).padStart(4, "0");
+  }
+}
+function extractParsePosition(err) {
+  const match = /position\s+(\d+)/.exec(safeErrorToString(err));
+  return match ? Number(match[1]) : null;
+}
+function safeErrorToString(e) {
+  if (e instanceof Error) {
+    const msg = readErrorField(e, "message");
+    if (typeof msg === "string" && msg.length > 0) return msg;
+    const name = readErrorField(e, "name");
+    if (typeof name === "string" && name.length > 0) return name;
+    return "[Error]";
+  }
+  try {
+    return String(e);
+  } catch {
+    try {
+      return Object.prototype.toString.call(e);
+    } catch {
+      return "[unstringifiable error]";
+    }
+  }
+}
+function readErrorField(e, key) {
+  try {
+    return e[key];
+  } catch {
+    return void 0;
+  }
 }
 function sanitizeRankerError(err, sanitizeRankerErrors) {
   if (sanitizeRankerErrors === false) {
@@ -459,8 +707,6 @@ function normalizeTitleKey(title) {
 function entitySummaryMetaKey(entityId) {
   return `entity_summary:${entityId}`;
 }
-
-// src/services/ImportExportService.ts
 var MAX_EMBEDDING_BLOB_BYTES = 32 * 1024;
 var IMPORT_TITLE_MAX = 500;
 var IMPORT_BODY_MAX = 8e3;
@@ -680,7 +926,23 @@ var ImportExportService = class {
           access_count: fact.access_count,
           deleted_at: fact.deleted_at,
           embedding_blob: blobData ?? void 0,
-          okf_type: fact.okf_type ?? null
+          okf_type: fact.okf_type ?? null,
+          // OKF v0.2 — forwarded as-is; parseOkfBundle / the caller is responsible for
+          // populating these per spec, importDump does not derive or validate them.
+          lifecycle_status: fact.lifecycle_status ?? "stable",
+          stale_after: fact.stale_after ?? null,
+          generated_by: fact.generated_by ?? null,
+          okf_sources: fact.okf_sources ?? [],
+          okf_verified: fact.okf_verified ?? [],
+          okf_usage_window: fact.okf_usage_window ?? null,
+          // last_verified_at/_by are DERIVED mirrors of `okf_verified` per spec
+          // §5.3. Recomputing here (instead of trusting the payload field) closes
+          // the invariant that a raw importDump cannot carry a
+          // last_verified_by that contradicts its own okf_verified list.
+          ...(() => {
+            const latest = coreOkf.latestVerified(fact.okf_verified ?? [], Date.now());
+            return { last_verified_at: latest?.at ?? null, last_verified_by: latest?.by ?? null };
+          })()
         };
         await this.entryRepo.upsertForImport(factObj, tx);
         if (blobData != null) {
@@ -730,7 +992,19 @@ var ImportExportService = class {
             updated_at: safeUpdatedAt,
             resolved_at: task.resolved_at,
             deleted_at: task.deleted_at,
-            okf_type: task.okf_type ?? null
+            okf_type: task.okf_type ?? null,
+            // OKF v0.2
+            lifecycle_status: task.lifecycle_status ?? "stable",
+            stale_after: task.stale_after ?? null,
+            generated_by: task.generated_by ?? null,
+            okf_sources: task.okf_sources ?? [],
+            okf_verified: task.okf_verified ?? [],
+            okf_usage_window: task.okf_usage_window ?? null,
+            // Derived mirrors — see fact branch above; same invariant.
+            ...(() => {
+              const latest = coreOkf.latestVerified(task.okf_verified ?? [], Date.now());
+              return { last_verified_at: latest?.at ?? null, last_verified_by: latest?.by ?? null };
+            })()
           },
           tx,
           safeUpdatedAt
@@ -942,7 +1216,7 @@ Return ONLY a valid JSON object matching this schema:
 {
   "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
 }
-Extract verbatim factual content. Do not return markdown, just raw JSON.`;
+Extract verbatim factual content. JSON escaping rules: every literal " character in the source must be escaped as \\" inside any JSON string body, and every literal newline as \\n. Source prose containing quotes (e.g. a worked example with "...") must still be reproduced exactly \u2014 re-escape, do not omit. Do not return markdown, just raw JSON.`;
 var ONTOLOGY_BACKFILL_SYSTEM_PROMPT = `You are a knowledge classification agent. You will receive existing memory facts that currently have no ontology type. For each input fact { "id", "title", "body", "tags" }, assign the best matching okf_type from the ontology manifest and optionally propose edges to related facts by title.
 Return ONLY a valid JSON object matching this schema:
 {
@@ -951,7 +1225,7 @@ Return ONLY a valid JSON object matching this schema:
   ]
 }
 If no manifest type fits a fact, omit that fact from "classifications" entirely \u2014 do not guess.
-Do not return markdown, just raw JSON.`;
+When echoing an existing fact's title verbatim into "target_title", preserve every JSON escape sequence (\\", \\n, \\\\, \\/) exactly as it appeared in the input body \u2014 do not strip backslashes, do not add unescaped quotes. Do not return markdown, just raw JSON.`;
 
 // src/services/PromptService.ts
 var PromptService = class {
@@ -1064,6 +1338,16 @@ var DEFAULT_MAX_CHUNK_LENGTH = 12e3;
 var DEFAULT_CHUNK_OVERLAP = 400;
 
 // src/services/IngestionService.ts
+function zeroChunkResult(duplicateOf) {
+  const result = {
+    truncated: false,
+    chunks: 0,
+    ingestedChunks: 0,
+    failedChunks: 0
+  };
+  if (duplicateOf !== void 0) result.duplicateOf = duplicateOf;
+  return result;
+}
 var IngestionService = class {
   constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, metadataRepo, edgeRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
@@ -1104,113 +1388,110 @@ var IngestionService = class {
           if (onDuplicateHash === "throw") {
             throw new WikiDuplicateHashError({ canonical, sourceHash, entityId });
           }
-          return { truncated: false, chunks: 0, duplicateOf: canonical };
+          return zeroChunkResult(canonical);
         }
       }
       const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
-      if (chunks.length === 0) return { truncated: false, chunks: 0 };
+      if (chunks.length === 0) return zeroChunkResult();
+      const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
       const chunkResults = await withConcurrency(
-        chunks.map((chunk) => async () => {
-          const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
+        chunks.map((chunk, chunkIndex) => async () => {
           const { systemPrompt, userPrompt } = this.promptService.buildIngestPrompt(
             chunk,
             params.promptOverride,
             ontologyContext
           );
-          const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
-          const result = parseJsonResponse(responseText);
-          return {
-            facts: (Array.isArray(result.facts) ? result.facts : []).map(validateFact).filter((f) => f !== null),
-            ontology_updates: result.ontology_updates
-          };
+          try {
+            const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+            const result2 = parseJsonResponse(responseText);
+            return {
+              status: "ok",
+              facts: (Array.isArray(result2.facts) ? result2.facts : []).map(validateFact).filter((f) => f !== null),
+              ontology_updates: result2.ontology_updates
+            };
+          } catch (e) {
+            const failure = e instanceof WikiParseError ? {
+              chunkIndex,
+              sourceRef,
+              source: "parse",
+              tier: e.tier,
+              position: e.position,
+              message: e.message
+            } : {
+              chunkIndex,
+              sourceRef,
+              source: "llm",
+              // `safeErrorToString` is a non-throwing coercion: an LLM
+              // provider may reject with a non-Error value, and even
+              // `String(e)` itself can throw when `e.toString()` throws.
+              // Letting such an exception escape this catch would cause
+              // `withConcurrency` to reject, discarding every sibling
+              // chunk's results — the exact failure mode this per-chunk
+              // try/catch exists to prevent. Keeping the value in the
+              // `ChunkFailure` preserves the typed diagnostic for
+              // callers (see parseFailures) without unwinding the loop.
+              position: null,
+              message: safeErrorToString(e)
+            };
+            const total = chunks.length;
+            const tags = [];
+            if (failure.tier) tags.push(`tier=${failure.tier}`);
+            if (failure.position !== null) tags.push(`position=${failure.position}`);
+            const tagsSuffix = tags.length > 0 ? `; ${tags.join(" ")}` : "";
+            console.warn(
+              `[WikiMemory] ingest chunk ${chunkIndex + 1}/${total} ${failure.source} failed (sourceRef=${sourceRef}${tagsSuffix})`
+            );
+            return { status: "failed", error: failure };
+          }
         }),
         chunkConcurrency
       );
+      let ingestedChunks = 0;
+      let failedChunks = 0;
+      const failures = [];
       const seen = /* @__PURE__ */ new Set();
       const orderedChunkFacts = [];
-      for (const chunkResult of chunkResults) {
+      for (const slot of chunkResults) {
+        if (slot.status === "failed") {
+          failedChunks++;
+          failures.push(slot.error);
+          continue;
+        }
+        ingestedChunks++;
         const dedupedFacts = [];
-        for (const fact of chunkResult.facts) {
+        for (const fact of slot.facts) {
           const normalizedTitle = normalizeTitleKey(fact.title);
           if (!seen.has(normalizedTitle)) {
             seen.add(normalizedTitle);
             dedupedFacts.push(fact);
           }
         }
-        orderedChunkFacts.push({ facts: dedupedFacts, ontology_updates: chunkResult.ontology_updates });
+        orderedChunkFacts.push({ facts: dedupedFacts, ontology_updates: slot.ontology_updates });
+      }
+      if (failedChunks === chunks.length) {
+        throw new WikiIngestEmptyError({
+          parseFailures: failures,
+          sourceRef,
+          chunks: chunks.length
+        });
       }
-      const now = Date.now();
       const insertedFacts = [];
       const deletedSourceFactIds = [];
       try {
-        await this.db.withTransactionAsync(async (tx) => {
-          deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
-          const titleIndex = /* @__PURE__ */ new Map();
-          const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx, sourceRef);
-          for (const existing of existingFacts) {
-            titleIndex.set(normalizeTitleKey(existing.title), {
-              id: existing.id,
-              okf_type: existing.okf_type ?? null
-            });
-          }
-          let ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
-          let { mode, manifest } = ontologyState;
-          const hostNodes = [];
-          const rawEdgeRequests = [];
-          for (const { facts, ontology_updates } of orderedChunkFacts) {
-            if (mode === "emergent" && ontology_updates && this.ontologyService) {
-              manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontology_updates, tx);
-              ontologyState = await this.ontologyService.getEffectiveState(entityId, tx);
-              mode = ontologyState.mode;
-            }
-            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_");
-              hostNodes.push({
-                id,
-                type: ontologyFact.okf_type ?? "",
-                title: fact.title,
-                body: fact.body,
-                // Forward the LLM-extracted tags/confidence through the
-                // extracted-shape upsertGraphCore path so the entries row
-                // stores them (search filterability, heal-candidate
-                // selection, runReembed embedding-text signal). The public
-                // WikiMemory.upsertGraph API doesn't accept tags/confidence
-                // — host-supplied deterministic nodes default to [] and
-                // 'certain' as documented.
-                tags: fact.tags,
-                confidence: fact.confidence
-              });
-              insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
-              titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
-              if (normalized.edges.length > 0) {
-                rawEdgeRequests.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
-              }
-            }
-          }
-          const hostEdges = [];
-          for (const req of rawEdgeRequests) {
-            const resolved = this.ontologyService?.resolveEdges(
-              entityId,
-              req.sourceId,
-              req.sourceType,
-              req.edges,
-              manifest,
-              titleIndex,
-              now
-            ) ?? [];
-            for (const e of resolved) {
-              hostEdges.push({ type: e.edge_type, sourceId: e.source_id, targetId: e.target_id });
-            }
-          }
-          await this.upsertGraphCore(
-            entityId,
-            { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
-            tx,
-            { strict: false }
-          );
-        });
+        if (failedChunks === 0) {
+          const fullResult = await this.db.withTransactionAsync(async (tx) => {
+            return await this.runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx);
+          });
+          deletedSourceFactIds.push(...fullResult.deletedSourceFactIds);
+          insertedFacts.push(...fullResult.insertedFacts);
+        } else {
+          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);
+          });
+          insertedFacts.push(...partialResult.insertedDescriptors);
+        }
       } catch (err) {
         const sqliteCode = err instanceof WikiTransactionError ? err.sqliteErrorCode : extractSqliteCode(err);
         if (sqliteCode !== "SQLITE_CONSTRAINT_UNIQUE") throw err;
@@ -1219,22 +1500,31 @@ var IngestionService = class {
         if (onDuplicateHash === "throw" || onDuplicateHash === "ingest") {
           throw new WikiDuplicateHashError({ canonical, sourceHash, entityId });
         }
-        return { truncated: false, chunks: 0, duplicateOf: canonical };
+        return zeroChunkResult(canonical);
       }
       await this.searchService.sync(entityId);
-      const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
-      for (const factId of uniqueDeletedSourceFactIds) {
-        try {
-          await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
-        } catch (hookErr) {
-          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+      if (failedChunks === 0) {
+        const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
+        for (const factId of uniqueDeletedSourceFactIds) {
+          try {
+            await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
+          } catch (hookErr) {
+            console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+          }
         }
       }
       for (const fact of insertedFacts) {
         await this.embeddingService.embedFact(fact);
       }
       this.searchService.evictCache(entityId);
-      return { truncated, chunks: chunks.length };
+      const result = {
+        truncated,
+        chunks: chunks.length,
+        ingestedChunks,
+        failedChunks
+      };
+      if (failedChunks > 0) result.parseFailures = failures;
+      return result;
     } finally {
       releaseIngestLocks();
     }
@@ -1359,6 +1649,156 @@ var IngestionService = class {
       superseded: deletedFactIds.length + deletedEdgeCount
     };
   }
+  /**
+   * Full supersession + ownership path: identical to the pre-issue-#92 behavior
+   * for the happy path. Called from the `failedChunks === 0` branch of
+   * `ingestDocument`. Runs INSIDE the caller's tx.
+   *
+   * Returns `{ deletedSourceFactIds, insertedFacts }` so the caller can fire
+   * post-commit hooks (embedding lifecycle) AFTER the transaction commits.
+   * On the partial path the caller never invokes this method; the empty
+   * arrays stay empty.
+   */
+  async runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx) {
+    const deletedSourceFactIds = [];
+    const insertedFacts = [];
+    deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
+    const titleIndex = /* @__PURE__ */ new Map();
+    const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx, sourceRef);
+    for (const existing of existingFacts) {
+      titleIndex.set(normalizeTitleKey(existing.title), {
+        id: existing.id,
+        okf_type: existing.okf_type ?? null
+      });
+    }
+    let ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+    let { mode, manifest } = ontologyState;
+    const hostNodes = [];
+    const rawEdgeRequests = [];
+    const now = Date.now();
+    for (const { facts, ontology_updates } of orderedChunkFacts) {
+      if (mode === "emergent" && ontology_updates && this.ontologyService) {
+        manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontology_updates, tx);
+        ontologyState = await this.ontologyService.getEffectiveState(entityId, tx);
+        mode = ontologyState.mode;
+      }
+      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_");
+        hostNodes.push({
+          id,
+          type: ontologyFact.okf_type ?? "",
+          title: fact.title,
+          body: fact.body,
+          // Forward the LLM-extracted tags/confidence through the
+          // extracted-shape upsertGraphCore path so the entries row
+          // stores them (search filterability, heal-candidate
+          // selection, runReembed embedding-text signal). The public
+          // WikiMemory.upsertGraph API doesn't accept tags/confidence
+          // — host-supplied deterministic nodes default to [] and
+          // 'certain' as documented.
+          tags: fact.tags,
+          confidence: fact.confidence
+        });
+        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
+        if (normalized.edges.length > 0) {
+          rawEdgeRequests.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+        }
+      }
+    }
+    const hostEdges = [];
+    for (const req of rawEdgeRequests) {
+      const resolved = this.ontologyService?.resolveEdges(
+        entityId,
+        req.sourceId,
+        req.sourceType,
+        req.edges,
+        manifest,
+        titleIndex,
+        now
+      ) ?? [];
+      for (const e of resolved) {
+        hostEdges.push({ type: e.edge_type, sourceId: e.source_id, targetId: e.target_id });
+      }
+    }
+    await this.upsertGraphCore(
+      entityId,
+      { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
+      tx,
+      { strict: false }
+    );
+    return { deletedSourceFactIds, insertedFacts };
+  }
+  /**
+   * Partial-commit path for `ingestDocument`. Inserts ONLY facts whose
+   * normalized title is not already in the live set for this (entityId,
+   * sourceRef). Does NOT call `entryRepo.softDeleteBySource` (no
+   * supersession) and does NOT call `sourceRefIndexRepo.upsert` (no
+   * ownership). Edges are NOT resolved on this path (no ontology-context
+   * build, no `resolveEdges`, no `mergeEmergentUpdates`). Stale edges from
+   * prior attempts are recovered on the next full run's supersession.
+   *
+   * Source-hash is stored as NULL on partial rows. `findLatestSourceHash`
+   * reads from the most recently updated live row for the sourceRef, so
+   * storing the incoming hash here would cause `hasChanged` to return
+   * `false` on a same-hash retry — the failed chunks would never get a
+   * second chance. With NULL, a retry sees `storedHash === null`, `hasChanged`
+   * returns `true`, and the partial commit's sibling rows remain live
+   * (deduped, not superseded) for the next attempt to extend.
+   *
+   * Runs INSIDE the caller's `tx`. Does not open a nested transaction.
+   * Returns `{ inserted, skippedDuplicate }` for observability.
+   */
+  async appendPartialFacts(entityId, sourceRef, dedupedFacts, tx) {
+    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)));
+    let inserted = 0;
+    let skippedDuplicate = 0;
+    const now = Date.now();
+    const insertedDescriptors = [];
+    for (const fact of dedupedFacts) {
+      const normalizedTitle = normalizeTitleKey(fact.title);
+      if (liveTitles.has(normalizedTitle)) {
+        skippedDuplicate++;
+        continue;
+      }
+      liveTitles.add(normalizedTitle);
+      const id = generateId("fact_");
+      const wikiFact = {
+        id,
+        entity_id: entityId,
+        title: fact.title,
+        body: fact.body,
+        tags: fact.tags,
+        confidence: fact.confidence,
+        source_type: "immutable_document",
+        // source_hash: null on partial rows — see method docstring. The
+        // full path stamps the actual hash; partial rows stay hash-less so
+        // `hasChanged` keeps returning true for retries.
+        source_hash: null,
+        source_ref: sourceRef,
+        created_at: now,
+        updated_at: now,
+        last_accessed_at: null,
+        access_count: 0,
+        deleted_at: null,
+        okf_type: null
+      };
+      await this.entryRepo.upsert(wikiFact, tx);
+      insertedDescriptors.push({
+        id,
+        entity_id: entityId,
+        title: fact.title,
+        body: fact.body,
+        tags: JSON.stringify(fact.tags)
+      });
+      inserted++;
+    }
+    return { inserted, skippedDuplicate, insertedDescriptors };
+  }
 };
 
 // src/utils/embedding.ts
@@ -1507,6 +1947,25 @@ var HEAL_ANCHOR_SEARCH_OVERFETCH = 4;
 var HEAL_MAX_PROMPT_CHARS = 4e4;
 var HEAL_BATCH_SIZE = 25;
 var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
+var SKIP_ERROR_LOG_CHARS = 4096;
+var formatSkipError = (err) => {
+  let base;
+  if (err instanceof Error || typeof err !== "object" && typeof err !== "function") {
+    base = safeErrorToString(err);
+  } else {
+    try {
+      const json = JSON.stringify(err);
+      base = typeof json === "string" ? json : safeErrorToString(err);
+    } catch {
+      base = safeErrorToString(err);
+    }
+  }
+  if (base.length > SKIP_ERROR_LOG_CHARS) {
+    const truncated = safeSlice(base, 0, SKIP_ERROR_LOG_CHARS);
+    return `${truncated}\u2026[+${base.length - SKIP_ERROR_LOG_CHARS} chars truncated]`;
+  }
+  return base;
+};
 var MaintenanceService = class {
   constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
@@ -1987,8 +2446,7 @@ var MaintenanceService = class {
       maxPromptChars: HEAL_MAX_PROMPT_CHARS,
       onSkip: (fact, err) => {
         console.warn(
-          `[WikiMemory] heal skipped ${entityId}/${fact.id}: response could not be bounded`,
-          err
+          `[WikiMemory] heal skipped ${entityId}/${fact.id}: response could not be bounded: ${formatSkipError(err)}`
         );
       }
     });
@@ -2126,8 +2584,7 @@ var MaintenanceService = class {
       maxPromptChars: ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS,
       onSkip: (fact, err) => {
         console.warn(
-          `[WikiMemory] ontology backfill skipped ${entityId}/${fact.id}: response could not be bounded`,
-          err
+          `[WikiMemory] ontology backfill skipped ${entityId}/${fact.id}: response could not be bounded: ${formatSkipError(err)}`
         );
       }
     });