@equationalapplications/core-llm-wiki 7.3.0 → 7.5.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-ht1qOvcD.mjs';
-export { C as ChunkFailure, D as DegradedRecord, E as EmbedFactResult, d as EmbedFailureKind, e as EmbeddingMarkerKind, f as EntityStatus, g as ExtractedFact, h as ExtractedFactEdge, i as ExtractedFactWithOntology, j as ExtractedTask, k as GraphTraversalOptions, H as HEAL_BATCH_SIZE, l as HEAL_RECHECK_MS, m as HOOK_TIMEOUT_MARKER, n as HealResult, I as IngestDocumentResult, L as LLMProvider, O as ONTOLOGY_BACKFILL_BATCH_SIZE, o as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, p as ONTOLOGY_BACKFILL_RECHECK_MS, q as OntologyBackfillResult, r as OntologyConfig, s as OntologyEdgeType, t as OntologyManifest, u as OntologyMode, v as OntologyNodeType, w as OntologyPromptContext, x as OntologyUpdates, P as PromptOverrides, y as PromptService, z as PrunePartialFailureError, A as ReembedResult, V as VectorRanker, B as VectorRankerFallback, J as VectorRankerRankArgs, K as VectorRankerSemanticResult, N as WikiBusyError, Q as WikiBusyOperation, T as WikiCheckpoint, U as WikiConfig, X as WikiDiagnostic, Y as WikiDiagnosticCode, Z as WikiDiagnosticDetail, _ as WikiDiagnosticOperation, $ as WikiDiagnosticSeverity, a0 as WikiDiagnosticTrigger, a1 as WikiDuplicateHashError, a2 as WikiEdge, a3 as WikiEvent, a4 as WikiFact, a5 as WikiGraphNodeOwnershipConflict, a6 as WikiIngestEmptyError, a7 as WikiInvalidReadOptions, a8 as WikiMemoryTestAccess, a9 as WikiOutboxEvent, aa as WikiParseError, ab as WikiSourceRefHashCollision, ac as WikiStrictOntologyViolation, ad as WikiTask, ae as WikiTransactionError, af as validateManifest } from './testing-ht1qOvcD.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-ClpOUiLI.mjs';
+export { C as ChunkFailure, d as ClassifierAnswer, e as ClassifierQuestion, f as ClassifyRequest, g as ClassifyResponse, D as DegradedRecord, h as DraftPage, E as EmbedFactResult, i as EmbedFailureKind, j as EmbeddingMarkerKind, k as EntityStatus, l as ExtractedFact, m as ExtractedFactEdge, n as ExtractedFactWithOntology, o as ExtractedTask, p as GraphTraversalOptions, H as HEAL_BATCH_SIZE, q as HEAL_RECHECK_MS, r as HOOK_TIMEOUT_MARKER, s as HealResult, I as IngestDocumentResult, L as LLMProvider, O as ONTOLOGY_BACKFILL_BATCH_SIZE, t as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, u as ONTOLOGY_BACKFILL_RECHECK_MS, v as OntologyBackfillResult, w as OntologyConfig, x as OntologyEdgeType, y as OntologyManifest, z as OntologyMode, A as OntologyNodeType, B as OntologyPromptContext, J as OntologyUpdates, P as PromptOverrides, K as PromptService, N as PrunePartialFailureError, Q as ReembedResult, V as VectorRanker, T as VectorRankerFallback, U as VectorRankerRankArgs, X as VectorRankerSemanticResult, Y as WikiBusyError, Z as WikiBusyOperation, _ as WikiCheckpoint, $ as WikiConfig, a0 as WikiDiagnostic, a1 as WikiDiagnosticCode, a2 as WikiDiagnosticDetail, a3 as WikiDiagnosticOperation, a4 as WikiDiagnosticSeverity, a5 as WikiDiagnosticTrigger, a6 as WikiDraftNotFound, a7 as WikiDuplicateHashError, a8 as WikiEdge, a9 as WikiEvent, aa as WikiFact, ab as WikiGraphNodeOwnershipConflict, ac as WikiIngestEmptyError, ad as WikiInvalidReadOptions, ae as WikiMemoryTestAccess, af as WikiOutboxEvent, ag as WikiParseError, ah as WikiSourceRefHashCollision, ai as WikiStrictOntologyViolation, aj as WikiTask, ak as WikiTransactionError, al as validateManifest } from './testing-ClpOUiLI.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-ht1qOvcD.js';
-export { C as ChunkFailure, D as DegradedRecord, E as EmbedFactResult, d as EmbedFailureKind, e as EmbeddingMarkerKind, f as EntityStatus, g as ExtractedFact, h as ExtractedFactEdge, i as ExtractedFactWithOntology, j as ExtractedTask, k as GraphTraversalOptions, H as HEAL_BATCH_SIZE, l as HEAL_RECHECK_MS, m as HOOK_TIMEOUT_MARKER, n as HealResult, I as IngestDocumentResult, L as LLMProvider, O as ONTOLOGY_BACKFILL_BATCH_SIZE, o as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, p as ONTOLOGY_BACKFILL_RECHECK_MS, q as OntologyBackfillResult, r as OntologyConfig, s as OntologyEdgeType, t as OntologyManifest, u as OntologyMode, v as OntologyNodeType, w as OntologyPromptContext, x as OntologyUpdates, P as PromptOverrides, y as PromptService, z as PrunePartialFailureError, A as ReembedResult, V as VectorRanker, B as VectorRankerFallback, J as VectorRankerRankArgs, K as VectorRankerSemanticResult, N as WikiBusyError, Q as WikiBusyOperation, T as WikiCheckpoint, U as WikiConfig, X as WikiDiagnostic, Y as WikiDiagnosticCode, Z as WikiDiagnosticDetail, _ as WikiDiagnosticOperation, $ as WikiDiagnosticSeverity, a0 as WikiDiagnosticTrigger, a1 as WikiDuplicateHashError, a2 as WikiEdge, a3 as WikiEvent, a4 as WikiFact, a5 as WikiGraphNodeOwnershipConflict, a6 as WikiIngestEmptyError, a7 as WikiInvalidReadOptions, a8 as WikiMemoryTestAccess, a9 as WikiOutboxEvent, aa as WikiParseError, ab as WikiSourceRefHashCollision, ac as WikiStrictOntologyViolation, ad as WikiTask, ae as WikiTransactionError, af as validateManifest } from './testing-ht1qOvcD.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-ClpOUiLI.js';
+export { C as ChunkFailure, d as ClassifierAnswer, e as ClassifierQuestion, f as ClassifyRequest, g as ClassifyResponse, D as DegradedRecord, h as DraftPage, E as EmbedFactResult, i as EmbedFailureKind, j as EmbeddingMarkerKind, k as EntityStatus, l as ExtractedFact, m as ExtractedFactEdge, n as ExtractedFactWithOntology, o as ExtractedTask, p as GraphTraversalOptions, H as HEAL_BATCH_SIZE, q as HEAL_RECHECK_MS, r as HOOK_TIMEOUT_MARKER, s as HealResult, I as IngestDocumentResult, L as LLMProvider, O as ONTOLOGY_BACKFILL_BATCH_SIZE, t as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, u as ONTOLOGY_BACKFILL_RECHECK_MS, v as OntologyBackfillResult, w as OntologyConfig, x as OntologyEdgeType, y as OntologyManifest, z as OntologyMode, A as OntologyNodeType, B as OntologyPromptContext, J as OntologyUpdates, P as PromptOverrides, K as PromptService, N as PrunePartialFailureError, Q as ReembedResult, V as VectorRanker, T as VectorRankerFallback, U as VectorRankerRankArgs, X as VectorRankerSemanticResult, Y as WikiBusyError, Z as WikiBusyOperation, _ as WikiCheckpoint, $ as WikiConfig, a0 as WikiDiagnostic, a1 as WikiDiagnosticCode, a2 as WikiDiagnosticDetail, a3 as WikiDiagnosticOperation, a4 as WikiDiagnosticSeverity, a5 as WikiDiagnosticTrigger, a6 as WikiDraftNotFound, a7 as WikiDuplicateHashError, a8 as WikiEdge, a9 as WikiEvent, aa as WikiFact, ab as WikiGraphNodeOwnershipConflict, ac as WikiIngestEmptyError, ad as WikiInvalidReadOptions, ae as WikiMemoryTestAccess, af as WikiOutboxEvent, ag as WikiParseError, ah as WikiSourceRefHashCollision, ai as WikiStrictOntologyViolation, aj as WikiTask, ak as WikiTransactionError, al as validateManifest } from './testing-ClpOUiLI.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.js

@@ -333,6 +333,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/db/serializedAdapter.ts
 function isDriverError(err) {
@@ -1757,16 +1765,52 @@ var EntryRepository = class extends BaseRepository {
       `UPDATE ${this.prefix}entries SET source_type = 'librarian_inferred' WHERE source_type = 'agent_inferred';`
     ].join("\n");
   }
-  async findRecentByEntityIds(entityIds, limit, tx) {
+  async findRecentByEntityIds(entityIds, limit, tx, opts) {
     if (entityIds.length === 0) return [];
     const executor = this.getExecutor(tx);
     const placeholders = entityIds.map(() => "?").join(",");
+    const draftClause = opts?.excludeDrafts === true ? ` AND lifecycle_status != 'draft'` : "";
     const rows = await executor.getAllAsync(
-      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT ?`,
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL${draftClause} ORDER BY updated_at DESC LIMIT ?`,
       [...entityIds, limit]
     );
     return rows.map(mapRowToFact);
   }
+  /** IDs of live draft facts for the given entities (spec §5.1). Callers pass ≤ 100 entity ids. */
+  async findDraftIdsByEntityIds(entityIds, tx) {
+    if (entityIds.length === 0) return /* @__PURE__ */ new Set();
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    const rows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL AND lifecycle_status = 'draft'`,
+      [...entityIds]
+    );
+    return new Set(rows.map((r) => r.id));
+  }
+  /** Live drafts for one entity, newest first, keyset-paged by (created_at, id). */
+  async listDraftsByEntityId(entityId, limit, after, tx) {
+    const executor = this.getExecutor(tx);
+    const afterClause = after ? ` AND (created_at < ? OR (created_at = ? AND id < ?))` : "";
+    const args = after ? [entityId, after.createdAt, after.createdAt, after.id, limit] : [entityId, limit];
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND lifecycle_status = 'draft'${afterClause}
+       ORDER BY created_at DESC, id DESC LIMIT ?`,
+      args
+    );
+    return rows.map(mapRowToFact);
+  }
+  /** True iff `entryId` is a live draft owned by `entityId`. */
+  async isLiveDraft(entryId, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE id = ? AND entity_id = ? AND deleted_at IS NULL AND lifecycle_status = 'draft'`,
+      [entryId, entityId]
+    );
+    return row != null;
+  }
   /**
    * Live untyped facts eligible for ontology backfill, oldest first.
    * Skips facts checked within the recheck cooldown (ontology_checked_at > recheckCutoff).
@@ -2577,6 +2621,7 @@ var EdgeRepository = class extends BaseRepository {
             END
           ) >= ?
           AND n.source_type NOT IN (${excludeSourceTypesPlaceholders})
+          AND (? = 0 OR n.lifecycle_status != 'draft')
         WHERE w.depth < ?
           AND instr(w.visited, ',' || (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END) || ',') = 0
       )
@@ -2596,6 +2641,7 @@ var EdgeRepository = class extends BaseRepository {
       entityId,
       minConfidenceRank,
       ...opts.excludeSourceTypes,
+      opts.excludeDrafts === true ? 1 : 0,
       opts.maxDepth,
       opts.maxNodes
     ];
@@ -5066,6 +5112,51 @@ var IngestionService = class {
   }
 };
 
+// src/utils/classifier.ts
+var isUnit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+function validateClassifierAnswer(response, key, question) {
+  try {
+    if (response === null || typeof response !== "object") return { ok: false, reason: "malformed" };
+    const answers = response.answers;
+    if (answers === null || typeof answers !== "object") return { ok: false, reason: "missing_answer" };
+    if (!Object.prototype.hasOwnProperty.call(answers, key)) return { ok: false, reason: "missing_answer" };
+    const raw = answers[key];
+    if (raw === null || typeof raw !== "object") return { ok: false, reason: "missing_answer" };
+    const a = raw;
+    if (a.kind !== question.kind) return { ok: false, reason: "kind_mismatch" };
+    if (question.kind === "choice") {
+      if (typeof a.choice !== "string" || !question.options.includes(a.choice)) return { ok: false, reason: "choice_not_offered" };
+      if (!isUnit(a.confidence)) return { ok: false, reason: "invalid_probability" };
+      const probs = a.probabilities;
+      if (probs === null || typeof probs !== "object" || Array.isArray(probs)) return { ok: false, reason: "invalid_probability" };
+      const probabilities = {};
+      for (const [k, v] of Object.entries(probs)) {
+        if (!isUnit(v)) return { ok: false, reason: "invalid_probability" };
+        probabilities[k] = v;
+      }
+      return { ok: true, answer: { kind: "choice", choice: a.choice, confidence: a.confidence, probabilities } };
+    }
+    if (question.kind === "binary") {
+      if (!isUnit(a.probability)) return { ok: false, reason: "invalid_probability" };
+      return { ok: true, answer: { kind: "binary", probability: a.probability } };
+    }
+    const maxScore = question.levels.length - 1;
+    if (typeof a.score !== "number" || !Number.isFinite(a.score) || a.score < 0 || a.score > maxScore) {
+      return { ok: false, reason: "score_out_of_range" };
+    }
+    if (!isUnit(a.confidence)) return { ok: false, reason: "invalid_probability" };
+    if (!Array.isArray(a.probabilities) || !a.probabilities.every(isUnit)) return { ok: false, reason: "invalid_probability" };
+    return { ok: true, answer: { kind: "score", score: a.score, confidence: a.confidence, probabilities: a.probabilities.slice() } };
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+}
+function classifierStateForFact(fact) {
+  const parts = [fact.title, fact.body];
+  if (Array.isArray(fact.tags) && fact.tags.length > 0) parts.push(`Tags: ${fact.tags.join(", ")}`);
+  return parts.join("\n\n");
+}
+
 // src/services/BoundedLlmCall.ts
 var DEFAULT_BATCH_SIZE = 10;
 var ESTIMATED_OUTPUT_TOKENS_PER_ITEM = 150;
@@ -5948,7 +6039,7 @@ var MaintenanceService = class {
     if (!ontologyService) {
       return { ...zeroed, remaining: 0, deferred: 0 };
     }
-    const { mode } = await ontologyService.getEffectiveState(entityId);
+    const { mode, manifest: effectiveManifest } = await ontologyService.getEffectiveState(entityId);
     if (mode === "off") {
       const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
       return { ...zeroed, remaining: 0, deferred: counts2.deferred };
@@ -5958,6 +6049,14 @@ var MaintenanceService = class {
       const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
       return { ...zeroed, remaining: counts2.eligible, deferred: counts2.deferred };
     }
+    const classifierMode = options?.classifier ?? this.options.config?.ontology?.backfillClassifier ?? "llm";
+    const classify = this.options.llmProvider.classify;
+    if (classifierMode === "auto" && typeof classify === "function") {
+      const slugs = effectiveManifest.node_types.map((n) => n.type);
+      if (slugs.length > 0 && slugs.length <= 255) {
+        return this._runClassifierBackfill(entityId, candidates, effectiveManifest, now, recheckCutoff);
+      }
+    }
     const ontologyContext = await ontologyService.buildPromptContext(entityId);
     const toPromptShape = (f) => ({ id: f.id, title: f.title, body: f.body, tags: f.tags });
     const buildPrompt = (facts) => this.promptService.buildOntologyBackfillPrompt(
@@ -6036,6 +6135,87 @@ var MaintenanceService = class {
       deferred: counts.deferred
     };
   }
+  /**
+   * Classifier-mode backfill (spec §7.3): one `choice` question per untyped
+   * fact over the effective manifest's node-type slugs. Accepted answers go
+   * through `_applyOntologyBackfillBatch` exactly like LLM classifications.
+   * No edges are proposed.
+   */
+  async _runClassifierBackfill(entityId, candidates, manifest, now, recheckCutoff) {
+    const provider = this.options.llmProvider;
+    const rawMin = this.options.config?.ontology?.classifyMinConfidence;
+    const minConfidence = typeof rawMin === "number" && Number.isFinite(rawMin) && rawMin >= 0 && rawMin <= 1 ? rawMin : 0.5;
+    const rawConcurrency = this.options.config?.chunkConcurrency ?? 1;
+    const concurrency = Number.isFinite(rawConcurrency) && rawConcurrency >= 1 ? Math.floor(rawConcurrency) : 1;
+    const question = {
+      kind: "choice",
+      options: manifest.node_types.map((n) => n.type),
+      instructions: "Choose the ontology node type that best describes this fact.\n" + manifest.node_types.map((n) => `- ${n.type}: ${n.description}`).join("\n")
+    };
+    const outcomes = await withConcurrency(
+      candidates.map((fact) => async () => {
+        let response;
+        try {
+          response = await provider.classify({ state: classifierStateForFact(fact), questions: { okf_type: question } });
+        } catch {
+          return { fact, kind: "threw" };
+        }
+        const checked = validateClassifierAnswer(response, "okf_type", question);
+        if (!checked.ok) return { fact, kind: "invalid", reason: checked.reason };
+        if (checked.answer.kind !== "choice") return { fact, kind: "invalid", reason: "kind_mismatch" };
+        if (checked.answer.confidence < minConfidence) return { fact, kind: "low_confidence" };
+        return { fact, kind: "accepted", okfType: checked.answer.choice };
+      }),
+      concurrency
+    );
+    const attempted = outcomes.filter((o) => o.kind !== "threw").map((o) => o.fact);
+    const skipped = outcomes.length - attempted.length;
+    const classifications = outcomes.filter((o) => o.kind === "accepted").map((o) => ({ id: o.fact.id, okf_type: o.okfType }));
+    const invalidCount = outcomes.filter((o) => o.kind === "invalid").length;
+    let typed = 0;
+    let failedValidation = 0;
+    let edgesAdded = 0;
+    let aborted = false;
+    if (attempted.length > 0) {
+      const applied = await this._applyOntologyBackfillBatch(
+        entityId,
+        { batch: attempted, classifications, ontologyUpdates: void 0 },
+        now
+      );
+      aborted = applied.abortedOntologyOff;
+      if (!aborted) {
+        typed = applied.typed;
+        failedValidation = invalidCount + applied.failedValidation;
+        edgesAdded = applied.edgesAdded;
+      }
+    }
+    const diagBuffer = new DiagnosticBuffer();
+    const diagBase = { entityId, operation: "ontologyBackfill", trigger: "call" };
+    for (const o of outcomes) {
+      if (o.kind === "low_confidence") {
+        diagBuffer.push({ ...diagBase, code: "classification_low_confidence", detail: { factId: o.fact.id, reason: "below_threshold" } });
+      } else if (o.kind === "invalid") {
+        diagBuffer.push({ ...diagBase, code: "classification_invalid", detail: { factId: o.fact.id, reason: o.reason } });
+      } else if (o.kind === "threw") {
+        diagBuffer.push({ ...diagBase, code: "classification_invalid", detail: { factId: o.fact.id, reason: "classify_threw" } });
+      }
+    }
+    diagBuffer.flush(this.options);
+    const counts = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+    if (aborted) {
+      return { scanned: 0, typed: 0, failedValidation: 0, edgesAdded: 0, skipped, remaining: 0, deferred: counts.deferred };
+    }
+    this.searchService.evictCache(entityId);
+    return {
+      scanned: candidates.length,
+      typed,
+      failedValidation,
+      edgesAdded,
+      skipped,
+      remaining: counts.eligible,
+      deferred: counts.deferred
+    };
+  }
   /**
    * Applies one parsed backfill batch in its own transaction. Per-batch rather
    * than one transaction for the pass, so mergeEmergentUpdates semantics and
@@ -6739,8 +6919,7 @@ var EmbeddingService = class {
     }
   }
   async tryEmbedFact(fact, ctx) {
-    const embedFn = this.options.llmProvider.embed;
-    if (typeof embedFn !== "function") return { ok: false, kind: "no_provider" };
+    if (typeof this.options.llmProvider.embed !== "function") return { ok: false, kind: "no_provider" };
     let tagsStr;
     if (Array.isArray(fact.tags)) {
       tagsStr = fact.tags.join(" ");
@@ -6757,7 +6936,7 @@ var EmbeddingService = class {
     const text = clip(`${fact.title} ${fact.body} ${tagsStr}`.trim(), maxEmbedChars);
     let float32Vector;
     try {
-      const vector = await embedFn(text);
+      const vector = await this.options.llmProvider.embed(text);
       if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
         console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
         this.reportEmbed(ctx, fact, "embedding_failed", "invalid_vector");
@@ -6969,6 +7148,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;
@@ -7001,6 +7181,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,
@@ -7014,19 +7195,21 @@ var RetrievalService = class {
     const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
     const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
     const skipEmbed = weight === 0;
-    const embedFn = this.options.llmProvider.embed;
     let facts = [];
     let scoreByFactId;
     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) {
+      } else if (!skipEmbed && typeof this.options.llmProvider.embed === "function") {
         let rankerShouldRethrow = false;
         let pendingRankerFallbackError;
         try {
-          const queryVec = await embedFn(trimmedQuery);
+          const queryVec = await this.options.llmProvider.embed(trimmedQuery);
           if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
             throw new Error(
               "embed() returned an empty or non-finite vector. Falling back to keyword search."
@@ -7053,7 +7236,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 {
@@ -7075,9 +7258,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);
@@ -7107,7 +7290,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 }));
                   })
@@ -7321,7 +7504,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));
@@ -7362,6 +7545,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,
@@ -7424,8 +7608,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,
@@ -7449,7 +7633,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([
@@ -7485,6 +7669,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.
@@ -7881,6 +8068,7 @@ var GraphTraversalService = class {
       edgeTypes: options.edgeTypes,
       minConfidence: options.minTraversalConfidence ?? this.config.minTraversalConfidence ?? "tentative",
       excludeSourceTypes: options.excludeSourceTypes ?? this.config.excludeSourceTypes ?? [],
+      excludeDrafts: options.excludeDrafts ?? this.config.excludeDrafts ?? false,
       maxNodes
     };
     const { nodeIds, edges } = await this.edgeRepo.getNeighborhood(entityId, options.sourceId, opts);
@@ -8054,6 +8242,15 @@ var OkfTrustWritesRepository = class {
 
 // src/WikiMemory.ts
 var TABLE_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,30}_$/;
+function decodeDraftCursor(cursor) {
+  const sep = typeof cursor === "string" ? cursor.indexOf(":") : -1;
+  const createdAt = sep > 0 ? Number(cursor.slice(0, sep)) : Number.NaN;
+  const id = sep > 0 ? cursor.slice(sep + 1) : "";
+  if (!Number.isSafeInteger(createdAt) || id.length === 0) {
+    throw new TypeError("Invalid listDrafts cursor.");
+  }
+  return { createdAt, id };
+}
 var _testAccessNonTestEnvWarned;
 var WikiMemory = class {
   constructor(db, options) {
@@ -8598,6 +8795,43 @@ var WikiMemory = class {
   async setLifecycleStatus(entryId, entityId, status) {
     return this.okfTrustWrites.setLifecycleStatus(entryId, entityId, status);
   }
+  /**
+   * Live draft facts for one entity, newest first (spec §5.2). Default page
+   * size 50, clamped to [1, 500]. Pass `nextCursor` back unchanged for the next page.
+   */
+  async listDrafts(entityId, options) {
+    const rawLimit = options?.limit;
+    const limit = typeof rawLimit === "number" && Number.isFinite(rawLimit) ? Math.min(500, Math.max(1, Math.floor(rawLimit))) : 50;
+    const after = options?.cursor === void 0 ? null : decodeDraftCursor(options.cursor);
+    const rows = await this.entryRepo.listDraftsByEntityId(entityId, limit + 1, after);
+    const facts = rows.slice(0, limit);
+    const last = facts[facts.length - 1];
+    return {
+      facts,
+      nextCursor: rows.length > limit && last ? `${last.created_at}:${last.id}` : null
+    };
+  }
+  /**
+   * Promote a draft to `stable` and record who reviewed it, atomically
+   * (spec §5.2). Metadata writes only: `updated_at` is not bumped and no
+   * outbox event is pushed. Pass `by: 'human:<id>'` so `trustTier` becomes
+   * `'human-reviewed'`.
+   *
+   * @throws WikiDraftNotFound when no live draft with that id exists for the entity.
+   */
+  async promoteDraft(entryId, entityId, reviewer) {
+    const by = reviewer?.by;
+    if (typeof by !== "string" || by.trim().length === 0) {
+      throw new TypeError("promoteDraft requires reviewer.by to be a non-empty string.");
+    }
+    await this.db.withTransactionAsync(async (tx) => {
+      if (!await this.entryRepo.isLiveDraft(entryId, entityId, tx)) {
+        throw new WikiDraftNotFound();
+      }
+      await this.okfTrustWrites.setLifecycleStatus(entryId, entityId, "stable", tx);
+      await this.okfTrustWrites.writeOkfTrust(entryId, entityId, [{ by, at: (/* @__PURE__ */ new Date()).toISOString() }], tx);
+    });
+  }
   /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
   async setStaleAfter(entryId, entityId, date) {
     return this.okfTrustWrites.setStaleAfter(entryId, entityId, date);
@@ -9549,6 +9783,7 @@ exports.ONTOLOGY_BACKFILL_SYSTEM_PROMPT = ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
 exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
+exports.WikiDraftNotFound = WikiDraftNotFound;
 exports.WikiDuplicateHashError = WikiDuplicateHashError;
 exports.WikiGraphNodeOwnershipConflict = WikiGraphNodeOwnershipConflict;
 exports.WikiIngestEmptyError = WikiIngestEmptyError;