@equationalapplications/core-llm-wiki 7.5.0 → 7.7.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, BaseRepository, WikiGraphNodeOwnershipConflict, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, WikiTransactionError, extractSqliteCode } from './chunk-3P7FAKJA.mjs';
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-3P7FAKJA.mjs';
+import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, BaseRepository, WikiGraphNodeOwnershipConflict, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, WikiTransactionError, extractSqliteCode } from './chunk-VOSMYISQ.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-VOSMYISQ.mjs';
 import { appendRelatedSection, buildConceptDocument, buildLogMd, buildEntityIndexMd, buildRootIndexMd, isAllowedOkfPath, parseRootIndexMd, parseEntityIndexMd, parseConcept, splitRelatedSection, extractMarkdownLinks, parseLogMd, parseEventIdComment, latestVerified, formatSourcesJson, appendEventIdComment, parseVerifiedFlexible, parseCitationsList, deriveTrustTier, isStaleAfter } from '@equationalapplications/core-okf';
 
 // src/db/schema.ts
@@ -948,15 +948,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})`,
@@ -1395,6 +1396,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
@@ -2654,6 +2684,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;
@@ -2844,15 +2973,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,
@@ -3031,6 +3162,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
@@ -3431,6 +3617,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) {