@equationalapplications/core-llm-wiki 7.3.0 → 7.4.0

package/README.md

@@ -285,6 +285,31 @@ True cosine-range pure semantic ranking (including negative cosine values) is us
 **Pre-filtering optimization:**
 When `preFilterLimit: 50` is set with 1000 facts, cosine similarity is computed only for the top 50 MiniSearch keyword matches, reducing O(N) scoring to O(50).
 
+## Draft Review
+
+Facts can carry `lifecycle_status: 'draft'`, for example when a host marks model output as unreviewed. Drafts stay visible by default. To keep them out of results:
+
+```ts
+await wiki.read('user-1', 'deploy process', { excludeDrafts: true });
+await wiki.traverseGraph('user-1', { sourceId, excludeDrafts: true });
+// or engine-wide:
+createWiki(db, { llmProvider, config: { excludeDrafts: true } });
+```
+
+- On every `read()` path, drafts are removed **before** `maxResults`, `tierFloors`, and pre-filter cuts, so they never take slots from reviewed facts.
+- In traversal, drafts are dead ends. The starting fact is always returned.
+- Status is read from SQLite on every call. A promotion is visible immediately, with no re-indexing.
+
+Review API:
+
+```ts
+const { facts, nextCursor } = await wiki.listDrafts('user-1', { limit: 50 });
+await wiki.promoteDraft(facts[0].id, 'user-1', { by: 'human:alice' }); // → stable, trustTier 'human-reviewed'
+// Reject with setLifecycleStatus(id, entityId, 'deprecated') or forget().
+```
+
+`promoteDraft` throws `WikiDraftNotFound` when no live draft with that id exists for the entity. The error is contextless by design. Promotion does not change `updated_at`, so a promoted fact keeps its recency position.
+
 ## Pluggable Vector Retrieval
 
 When your entity corpus grows, in-process cosine similarity scoring becomes a bottleneck. The optional **`VectorRanker`** interface lets you delegate semantic ranking to [**sqlite-vec**](https://github.com/asg017/sqlite-vec), [**sqlite-vss**](https://github.com/asg017/sqlite-vss), or an external vector database while `WikiMemory` handles embedding validation, hybrid scoring, and tier-2 row hydration.

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

@@ -168,6 +168,14 @@ var WikiInvalidReadOptions = class _WikiInvalidReadOptions extends Error {
     Object.setPrototypeOf(this, _WikiInvalidReadOptions.prototype);
   }
 };
+var WikiDraftNotFound = class _WikiDraftNotFound extends Error {
+  constructor() {
+    super("No draft fact with that id exists for this entity.");
+    this.code = "WIKI_DRAFT_NOT_FOUND";
+    this.name = "WikiDraftNotFound";
+    Object.setPrototypeOf(this, _WikiDraftNotFound.prototype);
+  }
+};
 
 // src/utils/ids.ts
 var _injectedGetRandomValues = null;
@@ -4552,6 +4560,7 @@ function selectWithFloors(sortedRows, floors, maxResults) {
 }
 
 // src/services/RetrievalService.ts
+var EMPTY_ID_SET = /* @__PURE__ */ new Set();
 var RetrievalService = class {
   constructor(options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService) {
     this.options = options;
@@ -4584,6 +4593,7 @@ var RetrievalService = class {
     }
     const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
     const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
+    const excludeDrafts = (options?.excludeDrafts ?? config?.excludeDrafts ?? false) === true;
     const trimmedQuery = query.trim();
     const sanitizedTierFloors = trimmedQuery && exposeMetadata ? validateTierFloors(
       entityIds,
@@ -4603,6 +4613,9 @@ var RetrievalService = class {
     if (maxResults === 0) ; else if (trimmedQuery) {
       let usedEmbed = false;
       const scoredEntityIds = this._filterScoredEntities(entityIds, sanitizedTierWeights, options?.includeZeroWeightEntities);
+      const draftIds = excludeDrafts && scoredEntityIds.length > 0 ? await this.entryRepo.findDraftIdsByEntityIds(scoredEntityIds) : EMPTY_ID_SET;
+      const draftPad = draftIds.size;
+      const padLimit = (n) => n >= Number.MAX_SAFE_INTEGER ? n : n + draftPad;
       if (scoredEntityIds.length === 0) {
         usedEmbed = true;
       } else if (!skipEmbed && embedFn) {
@@ -4636,7 +4649,7 @@ var RetrievalService = class {
           let miniSearchScores;
           if (effectivePreFilterLimit !== void 0) {
             populateCache = false;
-            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER);
+            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER).filter((r) => !draftIds.has(r.id));
             if (preResults.length === 0) {
               candidateRows = null;
             } else {
@@ -4658,9 +4671,9 @@ var RetrievalService = class {
             }
           } else {
             if (useRanker) {
-              candidateRows = await this.entryRepo.findMetadataByEntityIds(scoredEntityIds);
+              candidateRows = this._withoutDrafts(await this.entryRepo.findMetadataByEntityIds(scoredEntityIds), draftIds);
             } else {
-              candidateRows = await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds);
+              candidateRows = this._withoutDrafts(await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds), draftIds);
             }
             if (weight !== void 0 && weight < 1) {
               miniSearchScores = this.searchService.getMiniSearchScores(trimmedQuery, scoredEntityIds);
@@ -4690,7 +4703,7 @@ var RetrievalService = class {
                       candidateRows: rowsForEntity,
                       weight,
                       miniSearchScores,
-                      limit: Math.max(maxResults * 2, maxResults + 50)
+                      limit: padLimit(Math.max(maxResults * 2, maxResults + 50))
                     });
                     return ranked.map((row) => ({ ...row, entity_id: scopedEntityId }));
                   })
@@ -4904,7 +4917,7 @@ var RetrievalService = class {
                   });
                 } else if (policy === "keyword") {
                   const hasActiveFloorsKeywordFallback = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
-                  const keywordOversampledLimit = hasActiveFloorsKeywordFallback ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
+                  const keywordOversampledLimit = hasActiveFloorsKeywordFallback ? Number.MAX_SAFE_INTEGER : padLimit(Math.max(maxResults * 2, maxResults + 50));
                   const preFilteredIds = effectivePreFilterLimit !== void 0 ? new Set(candidateRows.map((r) => r.id)) : void 0;
                   const keywordResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, keywordOversampledLimit);
                   const topResults = preFilteredIds === void 0 ? keywordResults : keywordResults.filter((r) => preFilteredIds.has(r.id));
@@ -4945,6 +4958,7 @@ var RetrievalService = class {
                 // read() re-sorts after applying tier weights
               });
             }
+            if (draftPad > 0) scored = scored.filter((s) => !draftIds.has(s.id));
             if (scored.length > 0) {
               scored = scored.map((row) => ({
                 ...row,
@@ -5007,8 +5021,8 @@ var RetrievalService = class {
       }
       if (!usedEmbed && scoredEntityIds.length > 0) {
         const hasActiveFloors = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
-        const fallbackOversampledLimit = hasActiveFloors ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
-        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit);
+        const fallbackOversampledLimit = hasActiveFloors ? Number.MAX_SAFE_INTEGER : padLimit(Math.max(maxResults * 2, maxResults + 50));
+        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit).filter((r) => !draftIds.has(r.id));
         const candidates = results.map((r) => ({
           id: r.id,
           entity_id: r.entity_id,
@@ -5032,7 +5046,7 @@ var RetrievalService = class {
         await this.entryRepo.trackAccess(ids, now);
       }
     } else {
-      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
+      facts = excludeDrafts ? await this.entryRepo.findRecentByEntityIds(entityIds, maxResults, void 0, { excludeDrafts: true }) : await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
     }
     const eventsLimit = Math.min(10 * entityIds.length, 100);
     const [tasks, events] = await Promise.all([
@@ -5068,6 +5082,9 @@ var RetrievalService = class {
   _tieBreakSort(items) {
     items.sort((a, b) => this._compareScoredRows(a, b));
   }
+  _withoutDrafts(rows, draftIds) {
+    return draftIds.size === 0 ? rows : rows.filter((row) => !draftIds.has(row.id));
+  }
   /**
    * Comparator for score + deterministic tie-break fields.
    * Negative return means "a ranks ahead of b" for descending score order.
@@ -5274,6 +5291,6 @@ var WriteService = class {
   }
 };
 
-export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-IAYO63DQ.mjs.map
-//# sourceMappingURL=chunk-IAYO63DQ.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-G5OR2VWD.mjs.map
+//# sourceMappingURL=chunk-G5OR2VWD.mjs.map