@equationalapplications/core-llm-wiki 7.5.0 → 7.7.0

package/dist/index.js

@@ -1144,15 +1144,16 @@ var EntryRepository = class extends BaseRepository {
    * fact, not only immutable_document rows, so the source-type restriction has
    * to be applied here, after retrieval.
    */
-  async findAnchorRowsByIds(entityId, ids, tx) {
+  async findAnchorRowsByIds(entityId, ids, tx, opts) {
     if (ids.length === 0) return [];
     const executor = this.getExecutor(tx);
+    const columns = opts?.withBody ? "id, title, source_ref, body, lifecycle_status" : "id, title, source_ref";
     const rows = [];
     for (let i = 0; i < ids.length; i += this.chunkSize) {
       const chunk = ids.slice(i, i + this.chunkSize);
       const placeholders = chunk.map(() => "?").join(", ");
       const chunkRows = await executor.getAllAsync(
-        `SELECT id, title, source_ref FROM ${this.prefix}entries
+        `SELECT ${columns} FROM ${this.prefix}entries
          WHERE entity_id = ? AND deleted_at IS NULL
            AND source_type = 'immutable_document'
            AND id IN (${placeholders})`,
@@ -1591,6 +1592,35 @@ var EntryRepository = class extends BaseRepository {
     }
     return out;
   }
+  /**
+   * Per source ref, the hash of the latest live row (same ordering as
+   * {@link findLatestSourceHashes}) and whether ANY live row carries a hash.
+   * Refs with no live row are absent. Chunked under the bind-variable limit.
+   */
+  async findSourceStates(entityId, sourceRefs, tx) {
+    const out = /* @__PURE__ */ new Map();
+    const deduped = Array.from(new Set(sourceRefs));
+    if (deduped.length === 0) return out;
+    const executor = this.getExecutor(tx);
+    const chunkLimit = Math.max(1, this.chunkSize - 1);
+    for (let i = 0; i < deduped.length; i += chunkLimit) {
+      const chunk = deduped.slice(i, i + chunkLimit);
+      const placeholders = chunk.map(() => "?").join(",");
+      const rows = await executor.getAllAsync(
+        `WITH ranked AS (
+           SELECT source_ref, source_hash,
+                  ROW_NUMBER() OVER (PARTITION BY source_ref ORDER BY updated_at DESC, id ASC) AS rn,
+                  MAX(CASE WHEN source_hash IS NOT NULL THEN 1 ELSE 0 END) OVER (PARTITION BY source_ref) AS any_hashed
+           FROM ${this.prefix}entries
+           WHERE entity_id = ? AND source_ref IN (${placeholders}) AND deleted_at IS NULL
+         )
+         SELECT source_ref, source_hash, any_hashed FROM ranked WHERE rn = 1`,
+        [entityId, ...chunk]
+      );
+      for (const r of rows) out.set(r.source_ref, { latestHash: r.source_hash, anyHashed: Number(r.any_hashed) === 1 });
+    }
+    return out;
+  }
   /**
    * Return the live source_refs for an entity that hold the given source_hash.
    * Used by the ingestDocument duplicate-hash guard and by hosts auditing
@@ -2703,6 +2733,10 @@ function typeSatisfies(declaredType, concreteType, manifest) {
   const parent = typeof def?.parent_type === "string" ? def.parent_type.trim().toLowerCase() : "";
   return parent !== "" && parent === declared;
 }
+function edgeTripleAllowed(manifest, edgeType, sourceType, targetType) {
+  const wanted = edgeType.trim().toLowerCase();
+  return (manifest.edge_types ?? []).some((d) => typeof d?.type === "string" && d.type.trim().toLowerCase() === wanted && typeof d.source_type === "string" && typeSatisfies(d.source_type, sourceType, manifest) && typeof d.target_type === "string" && typeSatisfies(d.target_type, targetType, manifest));
+}
 function validateManifest(manifest) {
   const nodeSlugs = /* @__PURE__ */ new Set();
   for (const node of manifest.node_types ?? []) {
@@ -4154,6 +4188,19 @@ function validateTags(tags) {
   if (!Array.isArray(tags)) return [];
   return tags.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0 && t.length <= 40).slice(0, 6);
 }
+var MAX_EVIDENCE_QUOTES = 10;
+function normalizeEvidence(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const out = [];
+  for (const entry of raw) {
+    if (typeof entry !== "string") continue;
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    out.push(trimmed);
+    if (out.length > MAX_EVIDENCE_QUOTES) break;
+  }
+  return out;
+}
 function validateFact(fact) {
   if (typeof fact?.title !== "string" || typeof fact?.body !== "string") return null;
   const title = clip(fact.title, 80);
@@ -4161,13 +4208,17 @@ function validateFact(fact) {
   if (!title || !body) return null;
   let confidence = fact.confidence;
   if (confidence !== "certain" && confidence !== "tentative") confidence = "inferred";
-  return {
+  const valid = {
     ...fact,
     title,
     body,
     confidence,
     tags: validateTags(fact.tags)
   };
+  const evidence = normalizeEvidence(fact.evidence);
+  if (evidence) valid.evidence = evidence;
+  else delete valid.evidence;
+  return valid;
 }
 function validateTask(task) {
   if (typeof task?.description !== "string") return null;
@@ -4212,6 +4263,60 @@ function jaccardScore(a, b) {
   return intersection.size / union.size;
 }
 
+// src/utils/grounding.ts
+var GROUNDING_VERIFIER = "process:grounding-check";
+var WRITERS = ["ingest", "librarian", "heal"];
+function positiveInt(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}
+function resolveGrounding(config) {
+  if (!config || config.mode !== "draft") return null;
+  const writers = Array.isArray(config.writers) ? config.writers.filter((w) => WRITERS.includes(w)) : ["ingest"];
+  return {
+    writers: new Set(writers),
+    minEvidenceChars: positiveInt(config.minEvidenceChars, 20),
+    // Never ask for more quotes than checkGrounding accepts (MAX_EVIDENCE_QUOTES).
+    maxEvidence: Math.min(MAX_EVIDENCE_QUOTES, positiveInt(config.maxEvidence, 3)),
+    maxEvidenceChars: positiveInt(config.maxEvidenceChars, 300)
+  };
+}
+function normalizeForGrounding(text) {
+  return text.normalize("NFKC").replace(/\s+/g, " ").trim();
+}
+function buildGroundingCorpus(parts) {
+  return parts.filter((p) => typeof p === "string").map(normalizeForGrounding);
+}
+function checkGrounding(evidence, normalizedCorpus, cfg) {
+  const quotes = evidence ?? [];
+  if (quotes.length > MAX_EVIDENCE_QUOTES) return { status: "failed", reason: "too_many_quotes" };
+  if (quotes.length === 0) return { status: "missing", reason: "no_evidence" };
+  const qualifying = quotes.map(normalizeForGrounding).filter((q) => q.length >= cfg.minEvidenceChars);
+  if (qualifying.length === 0) return { status: "missing", reason: "evidence_too_short" };
+  if (qualifying.some((q) => !normalizedCorpus.some((part) => part.includes(q)))) {
+    return { status: "failed", reason: "quote_not_found" };
+  }
+  return {
+    status: "grounded",
+    retained: qualifying.slice(0, cfg.maxEvidence).map((q) => safeSlice(q, 0, cfg.maxEvidenceChars))
+  };
+}
+function groundingOutcome(verdict, now) {
+  if (verdict.status === "grounded") {
+    return {
+      trust: {
+        lifecycle_status: "stable",
+        okf_verified: [{ by: GROUNDING_VERIFIER, at: new Date(now).toISOString() }],
+        last_verified_at: now,
+        last_verified_by: GROUNDING_VERIFIER
+      }
+    };
+  }
+  return {
+    trust: { lifecycle_status: "draft" },
+    diagnostic: { code: verdict.status === "missing" ? "grounding_missing" : "grounding_failed", reason: verdict.reason }
+  };
+}
+
 // src/utils/diagnostics.ts
 var SEVERITY = {
   ingest_chunk_failed: "warn",
@@ -4341,17 +4446,40 @@ 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.
 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.`;
+var GROUNDING_SOURCE = {
+  ingest: { key: "facts", source: "the document chunk" },
+  librarian: { key: "facts", source: 'the "summary" text of the events' },
+  heal: { key: "newFacts", source: 'the "summary" text of the recent events or the "body" text of the document anchors' }
+};
+function groundingEvidenceBlock(writer, cfg) {
+  const { key, source } = GROUNDING_SOURCE[writer];
+  return `EVIDENCE REQUIREMENT: every object in "${key}" must also carry an "evidence" array of 1 to ${cfg.maxEvidence} quotes. Each quote must be an exact substring copied character-for-character from ${source} (the SOURCE section), at least ${cfg.minEvidenceChars} characters long. Do not paraphrase. Do not quote these instructions, the ontology manifest, or any existing fact. A fact whose quotes cannot be found in the SOURCE section is stored as an unreviewed draft.
+"evidence": ["exact substring copied from the SOURCE section"]`;
+}
 
 // src/utils/healConstants.ts
 var HEAL_MAX_ANCHORS = 50;
 var HEAL_ANCHORS_PER_CANDIDATE = 4;
 var HEAL_MAX_FACT_BODY_CHARS_L3 = 4e3;
 var HEAL_MAX_TASKS = 50;
+var HEAL_ANCHOR_BODY_CHARS = 800;
 
 // src/services/PromptService.ts
 var PromptService = class {
-  constructor(globalOverrides) {
+  constructor(globalOverrides, grounding = null) {
     this.globalOverrides = globalOverrides;
+    this.grounding = grounding;
+  }
+  /** The resolved grounding config when `writer` is in `grounding.writers`; otherwise null (spec §6.2). */
+  groundingFor(writer) {
+    return this.grounding?.writers.has(writer) ? this.grounding : null;
+  }
+  /** Appended after any override and after ontology context, so it is always last. */
+  appendGrounding(systemPrompt, writer) {
+    const cfg = this.groundingFor(writer);
+    return cfg ? `${systemPrompt}
+
+${groundingEvidenceBlock(writer, cfg)}` : systemPrompt;
   }
   hydrate(template, variables) {
     return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
@@ -4381,13 +4509,13 @@ ${ctx.ontologyModeInstructions}`;
     const hasDocumentChunk = /\{\{\s*documentChunk\s*\}\}/.test(template);
     if (hasDocumentChunk || this.hasOntologyPlaceholders(template)) {
       return {
-        systemPrompt: this.buildSystemPrompt(template, { documentChunk }, ontologyContext),
+        systemPrompt: this.appendGrounding(this.buildSystemPrompt(template, { documentChunk }, ontologyContext), "ingest"),
         userPrompt: hasDocumentChunk ? "Please extract the facts." : `Document Chunk:
 ${documentChunk}`
       };
     }
     return {
-      systemPrompt: this.appendOntology(template, ontologyContext),
+      systemPrompt: this.appendGrounding(this.appendOntology(template, ontologyContext), "ingest"),
       userPrompt: `Document Chunk:
 ${documentChunk}`
     };
@@ -4396,23 +4524,27 @@ ${documentChunk}`
     const template = runtimeOverride ?? this.globalOverrides?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT;
     const hasEvents = /\{\{\s*events\s*\}\}/.test(template);
     const hasCurrentFacts = /\{\{\s*currentFacts\s*\}\}/.test(template);
+    const eventsShown = hasEvents || !hasCurrentFacts;
+    const corpusField = this.groundingFor("librarian") ? { groundingCorpus: buildGroundingCorpus(eventsShown ? events.map(summaryOf) : []) } : {};
     if (hasEvents || hasCurrentFacts || this.hasOntologyPlaceholders(template)) {
       return {
-        systemPrompt: this.buildSystemPrompt(template, { events, currentFacts }, ontologyContext),
+        systemPrompt: this.appendGrounding(this.buildSystemPrompt(template, { events, currentFacts }, ontologyContext), "librarian"),
         userPrompt: hasEvents || hasCurrentFacts ? "Please synthesize the context." : `Events:
 ${JSON.stringify(events, null, 2)}
 
 Current Facts:
-${JSON.stringify(currentFacts, null, 2)}`
+${JSON.stringify(currentFacts, null, 2)}`,
+        ...corpusField
       };
     }
     return {
-      systemPrompt: this.appendOntology(template, ontologyContext),
+      systemPrompt: this.appendGrounding(this.appendOntology(template, ontologyContext), "librarian"),
       userPrompt: `Events:
 ${JSON.stringify(events, null, 2)}
 
 Current Facts:
-${JSON.stringify(currentFacts, null, 2)}`
+${JSON.stringify(currentFacts, null, 2)}`,
+      ...corpusField
     };
   }
   /**
@@ -4442,40 +4574,54 @@ ${JSON.stringify(currentFacts, null, 2)}`
     const effectiveEvents = attemptLevel >= 2 ? [] : recentEvents;
     const maxAnchors = Math.max(1, Math.min(HEAL_MAX_ANCHORS, healCandidates.length * HEAL_ANCHORS_PER_CANDIDATE));
     const effectiveAnchors = documentAnchors.slice(0, maxAnchors);
+    const template = runtimeOverride ?? this.globalOverrides?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT;
+    const hasRecentEvents = /\{\{\s*recentEvents\s*\}\}/.test(template);
+    const hasDocumentAnchors = /\{\{\s*documentAnchors\s*\}\}/.test(template);
+    const usesPlaceholders = /\{\{\s*healCandidates\s*\}\}/.test(template) || hasDocumentAnchors || /\{\{\s*allTasks\s*\}\}/.test(template) || hasRecentEvents;
+    const healGrounding = this.groundingFor("heal");
+    const promptAnchors = healGrounding ? effectiveAnchors.map(toGroundingAnchor) : effectiveAnchors;
+    const eventsShown = !usesPlaceholders || hasRecentEvents;
+    const anchorsShown = !usesPlaceholders || hasDocumentAnchors;
+    const groundingCorpus = healGrounding ? buildGroundingCorpus([
+      ...eventsShown ? effectiveEvents.map(summaryOf) : [],
+      ...anchorsShown ? effectiveAnchors.map((a, i) => ({ status: a?.lifecycle_status, shown: promptAnchors[i] })).filter((x) => x.status !== "draft").map((x) => x.shown?.body) : []
+    ]) : null;
     const { shapedCandidates, degraded } = applyBodyTruncation(
       healCandidates,
       attemptLevel,
       bodyTruncationChars
     );
-    const template = runtimeOverride ?? this.globalOverrides?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT;
-    if (/\{\{\s*healCandidates\s*\}\}/.test(template) || /\{\{\s*documentAnchors\s*\}\}/.test(template) || /\{\{\s*allTasks\s*\}\}/.test(template) || /\{\{\s*recentEvents\s*\}\}/.test(template)) {
+    const corpusField = groundingCorpus !== null ? { groundingCorpus } : {};
+    if (usesPlaceholders) {
       return {
         prompts: {
-          systemPrompt: this.hydrate(template, {
+          systemPrompt: this.appendGrounding(this.hydrate(template, {
             healCandidates: shapedCandidates,
-            documentAnchors: effectiveAnchors,
+            documentAnchors: promptAnchors,
             allTasks: effectiveTasks,
             recentEvents: effectiveEvents
-          }),
+          }), "heal"),
           userPrompt: "Please heal the memory graph."
         },
-        degraded
+        degraded,
+        ...corpusField
       };
     }
     return {
       prompts: {
-        systemPrompt: template,
+        systemPrompt: this.appendGrounding(template, "heal"),
         userPrompt: `Heal Candidates:
 ${JSON.stringify(shapedCandidates, null, 2)}
 Document Anchors (DO NOT MODIFY OR DELETE):
-${JSON.stringify(effectiveAnchors, null, 2)}
+${JSON.stringify(promptAnchors, null, 2)}
 All Tasks:
 ${JSON.stringify(effectiveTasks, null, 2)}
 Recent Events:
 ${JSON.stringify(effectiveEvents, null, 2)}
 The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`
       },
-      degraded
+      degraded,
+      ...corpusField
     };
   }
   buildOntologyBackfillPrompt(facts, runtimeOverride, ontologyContext) {
@@ -4494,6 +4640,21 @@ ${JSON.stringify(facts, null, 2)}`
 ${JSON.stringify(facts, null, 2)}`
     };
   }
+  /**
+   * The system prompt each writer would send, without hydrating data (spec
+   * §8.3). `buildSystemPrompt` with no variables hydrates only ontology
+   * placeholders and leaves data placeholders verbatim; heal never receives
+   * ontology context, matching `buildHealPrompt`.
+   */
+  buildInstructionTemplates(ontologyContext) {
+    const o = this.globalOverrides;
+    return {
+      ingest: this.appendGrounding(this.buildSystemPrompt(o?.ingestSystemPrompt ?? INGEST_SYSTEM_PROMPT, {}, ontologyContext), "ingest"),
+      librarian: this.appendGrounding(this.buildSystemPrompt(o?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT, {}, ontologyContext), "librarian"),
+      heal: this.appendGrounding(o?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT, "heal"),
+      ontologyBackfill: this.buildSystemPrompt(o?.ontologyBackfillSystemPrompt ?? ONTOLOGY_BACKFILL_SYSTEM_PROMPT, {}, ontologyContext)
+    };
+  }
 };
 function applyBodyTruncation(candidates, attemptLevel, bodyTruncationChars) {
   if (attemptLevel < 3) {
@@ -4525,6 +4686,19 @@ function applyBodyTruncation(candidates, attemptLevel, bodyTruncationChars) {
   }
   return { shapedCandidates, degraded };
 }
+function summaryOf(event) {
+  return event?.summary;
+}
+function toGroundingAnchor(anchor) {
+  if (typeof anchor !== "object" || anchor === null) return anchor;
+  const a = anchor;
+  return {
+    id: a.id,
+    title: a.title,
+    source_ref: a.source_ref,
+    body: typeof a.body === "string" ? safeSlice(a.body, 0, HEAL_ANCHOR_BODY_CHARS) : ""
+  };
+}
 
 // src/utils/chunkingDefaults.ts
 var DEFAULT_MAX_CHUNK_LENGTH = 12e3;
@@ -4554,7 +4728,7 @@ var IngestionService = class {
     this.jobManager = jobManager;
     this.embeddingService = embeddingService;
     this.ontologyService = ontologyService;
-    this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
+    this.promptService = promptService ?? new PromptService(this.options.config?.prompts, resolveGrounding(this.options.config?.grounding));
   }
   async ingestDocument(entityId, params, opts) {
     const sourceRef = normalizeSourceRef(params.sourceRef);
@@ -4587,6 +4761,7 @@ var IngestionService = class {
       const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
       if (chunks.length === 0) return zeroChunkResult();
       const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
+      const ingestGrounding = this.promptService.groundingFor("ingest");
       const chunkResults = await withConcurrency(
         chunks.map((chunk, chunkIndex) => async () => {
           const { systemPrompt, userPrompt } = this.promptService.buildIngestPrompt(
@@ -4610,11 +4785,16 @@ var IngestionService = class {
                 rejected.push({ itemIndex, reason: factRejectionReason(raw) });
               }
             });
+            const verdicts = ingestGrounding ? (() => {
+              const corpus = buildGroundingCorpus([chunk]);
+              return facts.map((f) => checkGrounding(f.evidence, corpus, ingestGrounding));
+            })() : [];
             return {
               status: "ok",
               facts,
               itemIndexes,
               rejected,
+              verdicts,
               ontology_updates: result2.ontology_updates
             };
           } catch (e) {
@@ -4659,6 +4839,7 @@ var IngestionService = class {
       const failures = [];
       const seen = /* @__PURE__ */ new Set();
       const orderedChunkFacts = [];
+      const groundingLedger = /* @__PURE__ */ new Map();
       const diagBuffer = new DiagnosticBuffer();
       const diagBase = { entityId, operation: "ingest", trigger: "call" };
       for (const [chunkIndex, slot] of chunkResults.entries()) {
@@ -4677,6 +4858,7 @@ var IngestionService = class {
           if (!seen.has(normalizedTitle)) {
             seen.add(normalizedTitle);
             dedupedFacts.push(fact);
+            if (ingestGrounding) groundingLedger.set(fact, { verdict: slot.verdicts[k], chunkIndex, itemIndex: slot.itemIndexes[k] });
           } else {
             diagBuffer.push({
               ...diagBase,
@@ -4713,7 +4895,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, diagBuffer);
+            return await this.runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx, diagBuffer, groundingLedger);
           });
           deletedSourceFactIds.push(...fullResult.deletedSourceFactIds);
           insertedFacts.push(...fullResult.insertedFacts);
@@ -4721,7 +4903,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, diagBuffer);
+            return await this.appendPartialFacts(entityId, sourceRef, flat, tx, diagBuffer, groundingLedger);
           });
           insertedFacts.push(...partialResult.insertedDescriptors);
         }
@@ -4863,7 +5045,8 @@ var IngestionService = class {
         last_accessed_at: null,
         access_count: 0,
         deleted_at: null,
-        okf_type: normalized.okf_type
+        okf_type: normalized.okf_type,
+        ...opts?.nodeTrust?.get(node.id)
       };
       wikiFacts.push(wikiFact);
     }
@@ -4954,9 +5137,10 @@ 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, diagBuffer) {
+  async runFullUpsertGraph(entityId, sourceRef, sourceHash, orderedChunkFacts, tx, diagBuffer, groundingLedger = /* @__PURE__ */ new Map()) {
     const deletedSourceFactIds = [];
     const insertedFacts = [];
+    const nodeTrust = /* @__PURE__ */ new Map();
     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);
@@ -5000,6 +5184,20 @@ var IngestionService = class {
           tags: fact.tags,
           confidence: fact.confidence
         });
+        const grounding = groundingLedger.get(fact);
+        if (grounding) {
+          const outcome = groundingOutcome(grounding.verdict, now);
+          nodeTrust.set(id, outcome.trust);
+          if (outcome.diagnostic) {
+            diagBuffer.push({
+              entityId,
+              operation: "ingest",
+              trigger: "call",
+              code: outcome.diagnostic.code,
+              detail: { factId: id, sourceRef, chunkIndex: grounding.chunkIndex, itemIndex: grounding.itemIndex, reason: outcome.diagnostic.reason }
+            });
+          }
+        }
         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) {
@@ -5031,7 +5229,7 @@ var IngestionService = class {
       entityId,
       { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
       tx,
-      { strict: false, diag: { buffer: diagBuffer, operation: "ingest" } }
+      { strict: false, diag: { buffer: diagBuffer, operation: "ingest" }, ...nodeTrust.size > 0 ? { nodeTrust } : {} }
     );
     return { deletedSourceFactIds, insertedFacts };
   }
@@ -5055,7 +5253,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, diagBuffer) {
+  async appendPartialFacts(entityId, sourceRef, dedupedFacts, tx, diagBuffer, groundingLedger = /* @__PURE__ */ new Map()) {
     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)));
@@ -5078,6 +5276,17 @@ var IngestionService = class {
       }
       liveTitles.add(normalizedTitle);
       const id = generateId("fact_");
+      const grounding = groundingLedger.get(fact);
+      const outcome = grounding ? groundingOutcome(grounding.verdict, now) : null;
+      if (grounding && outcome?.diagnostic) {
+        diagBuffer.push({
+          entityId,
+          operation: "ingest",
+          trigger: "call",
+          code: outcome.diagnostic.code,
+          detail: { factId: id, sourceRef, chunkIndex: grounding.chunkIndex, itemIndex: grounding.itemIndex, reason: outcome.diagnostic.reason }
+        });
+      }
       const wikiFact = {
         id,
         entity_id: entityId,
@@ -5096,7 +5305,8 @@ var IngestionService = class {
         last_accessed_at: null,
         access_count: 0,
         deleted_at: null,
-        okf_type: null
+        okf_type: null,
+        ...outcome?.trust
       };
       await this.entryRepo.upsert(wikiFact, tx);
       insertedDescriptors.push({
@@ -5264,7 +5474,7 @@ async function runBatched(args) {
     }
     let result;
     try {
-      result = parse(responseText, batch);
+      result = parse(responseText, batch, prompts);
     } catch (err) {
       await onFailure(batch, err, attemptLevel, false);
       return;
@@ -5345,7 +5555,7 @@ var MaintenanceService = class {
     this.jobManager = jobManager;
     this.embeddingService = embeddingService;
     this.ontologyService = ontologyService;
-    this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
+    this.promptService = promptService ?? new PromptService(this.options.config?.prompts, resolveGrounding(this.options.config?.grounding));
   }
   async runPrune(entityId, options) {
     this.jobManager.acquireLock("prune", entityId);
@@ -5650,8 +5860,10 @@ var MaintenanceService = class {
       };
     });
     const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
-    const { systemPrompt, userPrompt } = this.promptService.buildLibrarianPrompt(
-      events.reverse(),
+    const promptEvents = events.reverse();
+    const librarianGrounding = this.promptService.groundingFor("librarian");
+    const { systemPrompt, userPrompt, groundingCorpus: librarianCorpus = [] } = this.promptService.buildLibrarianPrompt(
+      promptEvents,
       currentFacts,
       promptOverride,
       ontologyContext
@@ -5720,6 +5932,10 @@ var MaintenanceService = class {
         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 grounding = librarianGrounding ? groundingOutcome(checkGrounding(fact.evidence, librarianCorpus, librarianGrounding), now) : null;
+        if (grounding?.diagnostic) {
+          diagBuffer.push({ ...diagBase, code: grounding.diagnostic.code, detail: { factId: id, itemIndex: validFactItemIndexes[k], reason: grounding.diagnostic.reason } });
+        }
         const factObj = {
           id,
           entity_id: entityId,
@@ -5735,7 +5951,8 @@ var MaintenanceService = class {
           last_accessed_at: null,
           access_count: 0,
           deleted_at: null,
-          okf_type: normalized.okf_type
+          okf_type: normalized.okf_type,
+          ...grounding?.trust
         };
         await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
@@ -5851,11 +6068,14 @@ var MaintenanceService = class {
     }
     const allTasks = await this.taskRepo.findAllPending([entityId], HEAL_MAX_TASKS);
     const recentEvents = await this.eventRepo.getRecent(entityId, 20);
+    const healGrounding = this.promptService.groundingFor("heal");
     const toPromptShape = (f) => {
       const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
-      return { ...rest, tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags };
+      const shown = healGrounding ? (({ lifecycle_status: _l, okf_verified: _v, last_verified_at: _a, last_verified_by: _b, ...r }) => r)(rest) : rest;
+      return { ...shown, tags: typeof shown.tags === "string" ? JSON.parse(shown.tags) : shown.tags };
     };
     const anchorCache = /* @__PURE__ */ new Map();
+    const corpusByPrompt = /* @__PURE__ */ new WeakMap();
     const degraded = [];
     const outcome = await runBatched({
       items: healCandidates,
@@ -5868,9 +6088,10 @@ var MaintenanceService = class {
           // not overfetch the same 200 keyword hits a 25-fact batch once did.
           // buildHealPrompt applies the matching cap on its side — values must match.
           Math.min(HEAL_MAX_ANCHORS, batch.length * HEAL_ANCHORS_PER_CANDIDATE),
-          anchorCache
+          anchorCache,
+          healGrounding !== null
         );
-        const { prompts, degraded: batchDegraded } = await this.promptService.buildHealPrompt(
+        const { prompts, degraded: batchDegraded, groundingCorpus } = await this.promptService.buildHealPrompt(
           batch.map(toPromptShape),
           documentAnchors,
           allTasks,
@@ -5880,16 +6101,18 @@ var MaintenanceService = class {
           bodyTruncationChars
         );
         degraded.push(...batchDegraded);
+        if (groundingCorpus !== void 0) corpusByPrompt.set(prompts, groundingCorpus);
         return prompts;
       },
       call: (prompts) => this.options.llmProvider.generateText(prompts),
-      parse: (responseText, batch) => {
+      parse: (responseText, batch, prompts) => {
         const result = parseJsonResponse(responseText);
         return {
           batch,
           downgraded: Array.isArray(result.downgraded) ? result.downgraded : [],
           deleted: Array.isArray(result.deleted) ? result.deleted : [],
-          newFacts: Array.isArray(result.newFacts) ? result.newFacts : []
+          newFacts: Array.isArray(result.newFacts) ? result.newFacts : [],
+          corpus: corpusByPrompt.get(prompts) ?? null
         };
       },
       maxOutputTokens: this.options.llmProvider.maxOutputTokens,
@@ -5904,6 +6127,7 @@ var MaintenanceService = class {
     const safeDeletedSet = /* @__PURE__ */ new Set();
     const newFacts = [];
     const newFactItemIndexes = [];
+    const newFactCorpora = [];
     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);
@@ -5911,6 +6135,7 @@ var MaintenanceService = class {
       batchResult.newFacts.forEach((raw, itemIndex) => {
         newFacts.push(raw);
         newFactItemIndexes.push(itemIndex);
+        newFactCorpora.push(batchResult.corpus);
       });
     }
     const safeDowngraded = Array.from(safeDowngradedSet);
@@ -5918,12 +6143,14 @@ var MaintenanceService = class {
     const diagBuffer = new DiagnosticBuffer();
     const validNewFacts = [];
     const validNewFactItemIndexes = [];
+    const validNewFactCorpora = [];
     newFacts.forEach((raw, k) => {
       const itemIndex = newFactItemIndexes[k];
       const valid = validateFact(raw);
       if (valid) {
         validNewFacts.push(valid);
         validNewFactItemIndexes.push(itemIndex);
+        validNewFactCorpora.push(newFactCorpora[k]);
       } else {
         diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { itemIndex, reason: factRejectionReason(raw) } });
       }
@@ -5953,6 +6180,10 @@ var MaintenanceService = class {
           continue;
         }
         const id = generateId("fact_");
+        const grounding = healGrounding ? groundingOutcome(checkGrounding(fact.evidence, validNewFactCorpora[k] ?? [], healGrounding), now) : null;
+        if (grounding?.diagnostic) {
+          diagBuffer.push({ ...diagBase, code: grounding.diagnostic.code, detail: { factId: id, itemIndex: validNewFactItemIndexes[k], reason: grounding.diagnostic.reason } });
+        }
         const factObj = {
           id,
           entity_id: entityId,
@@ -5967,7 +6198,8 @@ var MaintenanceService = class {
           updated_at: now,
           last_accessed_at: null,
           access_count: 0,
-          deleted_at: null
+          deleted_at: null,
+          ...grounding?.trust
         };
         await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
@@ -6331,7 +6563,7 @@ var MaintenanceService = class {
    * batches that reduce to the same query share one lookup. Caller-owned and
    * per-pass — see the call site in doRunHeal.
    */
-  async _selectHealAnchors(entityId, batch, cap = HEAL_MAX_ANCHORS, cache) {
+  async _selectHealAnchors(entityId, batch, cap = HEAL_MAX_ANCHORS, cache, withBodies = false) {
     const query = batch.map((f) => f.title).join(" ").trim();
     if (!query) return [];
     const cached = cache?.get(query);
@@ -6344,7 +6576,7 @@ var MaintenanceService = class {
     const hitIds = hits.map((h) => h.id);
     const anchors = [];
     if (hitIds.length > 0) {
-      const rows = await this.entryRepo.findAnchorRowsByIds(entityId, hitIds);
+      const rows = withBodies ? await this.entryRepo.findAnchorRowsByIds(entityId, hitIds, void 0, { withBody: true }) : await this.entryRepo.findAnchorRowsByIds(entityId, hitIds);
       const byId = new Map(rows.map((r) => [r.id, r]));
       for (const id of hitIds) {
         const row = byId.get(id);
@@ -8081,6 +8313,105 @@ var GraphTraversalService = class {
     return { nodes, edges: filteredEdges };
   }
 };
+
+// src/repositories/LintRepository.ts
+var LintRepository = class extends BaseRepository {
+  async countFactHealth(entityId) {
+    const row = await this.db.getFirstAsync(
+      `SELECT
+         SUM(CASE WHEN okf_type IS NULL THEN 1 ELSE 0 END) AS untyped,
+         SUM(CASE WHEN lifecycle_status = 'draft' THEN 1 ELSE 0 END) AS drafts,
+         SUM(CASE WHEN source_type = 'librarian_inferred'
+                   AND COALESCE(json_array_length(CASE WHEN json_valid(okf_verified) THEN okf_verified END), 0) = 0
+                  THEN 1 ELSE 0 END) AS unverified
+       FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL`,
+      [entityId]
+    );
+    return {
+      untypedFacts: Number(row?.untyped ?? 0),
+      drafts: Number(row?.drafts ?? 0),
+      unverifiedInferred: Number(row?.unverified ?? 0)
+    };
+  }
+  danglingWhere() {
+    const live = (col) => `EXISTS (SELECT 1 FROM ${this.prefix}entries n WHERE n.id = e.${col} AND n.entity_id = e.entity_id AND n.deleted_at IS NULL)`;
+    return `e.entity_id = ? AND (NOT ${live("source_id")} OR NOT ${live("target_id")})`;
+  }
+  async countDanglingEdges(entityId) {
+    const row = await this.db.getFirstAsync(
+      `SELECT COUNT(*) AS n FROM ${this.prefix}edges e WHERE ${this.danglingWhere()}`,
+      [entityId]
+    );
+    return Number(row?.n ?? 0);
+  }
+  async sampleDanglingEdgeIds(entityId, limit) {
+    const rows = await this.db.getAllAsync(
+      `SELECT e.id FROM ${this.prefix}edges e WHERE ${this.danglingWhere()} ORDER BY e.id ASC LIMIT ?`,
+      [entityId, limit]
+    );
+    return rows.map((r) => r.id);
+  }
+  /** Keyset page of edges whose endpoints are both live in this entity, with endpoint types. */
+  async pageLiveEdges(entityId, afterId, limit) {
+    return this.db.getAllAsync(
+      `SELECT e.id, e.edge_type, s.okf_type AS source_type, t.okf_type AS target_type
+         FROM ${this.prefix}edges e
+         JOIN ${this.prefix}entries s ON s.id = e.source_id AND s.entity_id = e.entity_id AND s.deleted_at IS NULL
+         JOIN ${this.prefix}entries t ON t.id = e.target_id AND t.entity_id = e.entity_id AND t.deleted_at IS NULL
+        WHERE e.entity_id = ? AND e.id > ?
+        ORDER BY e.id ASC
+        LIMIT ?`,
+      [entityId, afterId, limit]
+    );
+  }
+};
+
+// src/services/LintService.ts
+var LINT_SAMPLE_SIZE = 20;
+var LINT_PAGE_SIZE = 500;
+var LintService = class {
+  constructor(lintRepo, ontologyService) {
+    this.lintRepo = lintRepo;
+    this.ontologyService = ontologyService;
+  }
+  /**
+   * Read-only (spec §8.1). Manifest violations stream the entity's live-endpoint
+   * edges in keyset pages and check each triple in JS against the effective
+   * manifest. `getEffectiveState` is called without a transaction, so a seed
+   * manifest is cached, never persisted. Counts come from separate statements,
+   * not one snapshot.
+   */
+  async lint(entityId) {
+    const health = await this.lintRepo.countFactHealth(entityId);
+    const danglingEdges = await this.lintRepo.countDanglingEdges(entityId);
+    const danglingEdgeIds = danglingEdges > 0 ? await this.lintRepo.sampleDanglingEdgeIds(entityId, LINT_SAMPLE_SIZE) : [];
+    const { mode, manifest } = await this.ontologyService.getEffectiveState(entityId);
+    const constrained = mode !== "off" && ((manifest.node_types?.length ?? 0) > 0 || (manifest.edge_types?.length ?? 0) > 0);
+    let manifestViolations = 0;
+    const manifestViolationEdgeIds = [];
+    if (constrained) {
+      let after = "";
+      for (; ; ) {
+        const page = await this.lintRepo.pageLiveEdges(entityId, after, LINT_PAGE_SIZE);
+        for (const e of page) {
+          if (!edgeTripleAllowed(manifest, e.edge_type, e.source_type ?? "", e.target_type ?? "")) {
+            manifestViolations++;
+            if (manifestViolationEdgeIds.length < LINT_SAMPLE_SIZE) manifestViolationEdgeIds.push(e.id);
+          }
+        }
+        if (page.length < LINT_PAGE_SIZE) break;
+        after = page[page.length - 1].id;
+      }
+    }
+    return {
+      danglingEdges,
+      manifestViolations,
+      ...health,
+      sample: { danglingEdgeIds, manifestViolationEdgeIds }
+    };
+  }
+};
 var OkfTrustWritesRepository = class {
   constructor(db, prefix) {
     this.db = db;
@@ -8271,15 +8602,17 @@ var WikiMemory = class {
     this.eventRepo = new EventRepository(this.db, this.prefix);
     this.edgeRepo = new EdgeRepository(this.db, this.prefix);
     this.metadataRepo = new MetadataRepository(this.db, this.prefix);
+    this.lintRepo = new LintRepository(this.db, this.prefix);
     this.ontologyService = new OntologyService(
       this.metadataRepo,
       this.edgeRepo,
       options.config?.ontology
     );
+    this.lintService = new LintService(this.lintRepo, this.ontologyService);
     this.embeddingService = new EmbeddingService(this.db, this.options, this.entryRepo, this.metadataRepo);
     this.searchService = new SearchService(this.entryRepo);
     this.jobManager = new JobManager(this.prefix);
-    this.promptService = new PromptService(options.config?.prompts);
+    this.promptService = new PromptService(options.config?.prompts, resolveGrounding(options.config?.grounding));
     this.ingestionService = new IngestionService(
       this.db,
       this.prefix,
@@ -8458,6 +8791,61 @@ var WikiMemory = class {
       return { sourceRef: e.rawSourceRef, changed, duplicateOf: canonical };
     });
   }
+  /**
+   * Batch pending state per source (spec §8.2). `current` exactly when
+   * `hasChanged` is false; `partial` when live rows exist but none carries a
+   * hash (a first ingest with a failed chunk, or imported rows without a
+   * hash). A failed re-ingest of an already-hashed ref reports `changed`. Validation and raw-ref echo match
+   * batched `hasChanged`. Input order and duplicates are preserved. A
+   * non-array `sources`, or an entry that is not an object (including a hole
+   * in a sparse array), throws a `TypeError` before any SQL runs.
+   */
+  async pendingSources(entityId, sources) {
+    assertEntityId(entityId);
+    if (!Array.isArray(sources)) {
+      throw new TypeError("Invalid sources: must be an array of { sourceRef, sourceHash } objects.");
+    }
+    if (sources.length === 0) return [];
+    const normalized = Array.from(sources, (s, i) => {
+      if (s === null || typeof s !== "object") {
+        throw new TypeError(`Invalid sources[${i}]: must be a { sourceRef, sourceHash } object.`);
+      }
+      const { sourceRef: rawSourceRef, sourceHash: rawSourceHash } = s;
+      const sourceRef = normalizeSourceRef(rawSourceRef);
+      if (!sourceRef) {
+        const shown = typeof rawSourceRef === "string" ? JSON.stringify(rawSourceRef) : `<${typeof rawSourceRef}>`;
+        throw new Error(`Invalid sourceRef: ${shown}`);
+      }
+      const sourceHash = normalizeSourceHash(rawSourceHash);
+      if (!sourceHash) throw new Error("Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)");
+      return { rawSourceRef, sourceRef, sourceHash };
+    });
+    const states = await this.entryRepo.findSourceStates(entityId, normalized.map((n) => n.sourceRef));
+    return normalized.map((n) => {
+      const state = states.get(n.sourceRef);
+      let status;
+      if (!state) status = "new";
+      else if (!state.anyHashed) status = "partial";
+      else if (state.latestHash !== null && normalizeSourceHash(state.latestHash) === n.sourceHash) status = "current";
+      else status = "changed";
+      return { sourceRef: n.rawSourceRef, status };
+    });
+  }
+  /** Read-only maintenance report for one entity (spec §8.1). Reports, never repairs. */
+  async lint(entityId) {
+    assertEntityId(entityId);
+    return this.lintService.lint(entityId);
+  }
+  /**
+   * Effective system prompts for ingest, librarian, heal and ontology backfill
+   * (spec §8.3). Backs the `wiki_get_instructions` tool. Templates only;
+   * overrides are returned verbatim, so keep secrets out of `WikiConfig.prompts`.
+   */
+  async getInstructions(entityId) {
+    assertEntityId(entityId);
+    const ontologyContext = await this.ontologyService.buildPromptContext(entityId);
+    return this.promptService.buildInstructionTemplates(ontologyContext);
+  }
   /**
    * Returns the live source_refs for an entity, one row per ref, with the most
    * recently-updated live `source_hash` and a live fact count. Refs are sorted
@@ -8858,6 +9246,11 @@ var WikiMemory = class {
   }
 };
 _testAccessNonTestEnvWarned = new WeakMap();
+function assertEntityId(entityId) {
+  if (typeof entityId !== "string" || entityId.length === 0) {
+    throw new TypeError("Invalid entityId: must be a non-empty string.");
+  }
+}
 
 // src/utils/formatContext.ts
 function validateMaxOption(value, name) {