@equationalapplications/core-llm-wiki 7.2.1 → 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.
@@ -504,6 +529,29 @@ Notes:
 - A throwing callback is caught (logged via `console.error`) and does not block other subscribers or the underlying job.
 - Subscriptions are scoped to a single `entityId`. There is no wildcard or "all entities" form.
 
+## Diagnostics
+
+Pass `onDiagnostic` to receive typed, content-free reports of events core used to drop silently or only log: failed chunks, rejected facts and tasks, dedupe drops, dropped edges, embedding and host-hook failures, heal skips, and background-job failures.
+
+```ts
+const wiki = createWiki(db, {
+  llmProvider,
+  onDiagnostic: (d) => {
+    // d.code, d.severity ('info' | 'warn' | 'error'), d.operation, d.trigger ('call' | 'auto'),
+    // d.entityId, d.at, d.message, d.detail?: { factId, sourceRef, chunkIndex, itemIndex,
+    // edgeType, sourceNodeType, targetNodeType, reason, count, chunkIndexes }
+    telemetry.record(d);
+  },
+});
+```
+
+- **Content-free.** Diagnostics carry IDs, indexes, counts, ontology slugs and reason slugs only. They never carry titles, bodies, LLM output, provider error messages, or hashes of content.
+- **Isolated.** The hook is called synchronously. A throwing or rejecting hook never affects the operation, and its failure is logged with `console.warn`.
+- **After commit.** Transactional diagnostics are delivered after the operation's transaction commits. An operation that throws delivers none; the exception is the signal. `upsertGraph` runs in your transaction, so its diagnostics are delivered when it resolves. Disregard them if you roll back.
+- **`trigger`.** `'auto'` marks work started by `autoLibrarianThreshold` / `autoHealThreshold`. A failed background job is reported as `background_job_failed` with `operation` set to the job.
+- **Forward-compatible.** New codes may be added in minor releases; ignore codes you don't recognize.
+- **Console output is unchanged** when a hook is set and succeeds: every existing core line is identical. A throwing or rejecting hook adds only its own `console.warn`, and a non-function `onDiagnostic` warns once.
+
 ## Per-Entity Seeded Ontology
 
 Control how librarian and ingest passes classify facts and extract graph relationships. The system defaults to **`off`** so existing deployments behave unchanged.