@equationalapplications/core-llm-wiki 7.2.1 → 7.4.0

package/dist/{testing-DYeMd9d1.d.mts → testing-Dmh1kfkd.d.mts}

@@ -269,6 +269,11 @@ interface WikiConfig {
     traversalDirection?: 'inbound' | 'outbound' | 'both';
     /** Default source_type dead-end list for discovered traversal nodes. Default []. */
     excludeSourceTypes?: Array<WikiFact['source_type']>;
+    /**
+     * Engine default for `ReadOptions.excludeDrafts` and
+     * `GraphTraversalOptions.excludeDrafts`. Default false (drafts visible).
+     */
+    excludeDrafts?: boolean;
 }
 interface ReadOptions {
     maxResults?: number;
@@ -309,6 +314,12 @@ interface ReadOptions {
      * by `tierWeights: 0`, or a floor keyed to an entity not in `entityId`.
      */
     tierFloors?: Record<string, number>;
+    /**
+     * When true, facts whose `lifecycle_status` is `'draft'` are excluded before
+     * `maxResults`, `tierFloors` and every other cut, on every read path.
+     * Resolves call → `WikiConfig.excludeDrafts` → false.
+     */
+    excludeDrafts?: boolean;
 }
 interface WikiFact {
     id: string;
@@ -451,6 +462,12 @@ interface GraphTraversalOptions {
     minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
     /** source_type values to dead-end on for *discovered* nodes. Does not gate the anchor. Default []. */
     excludeSourceTypes?: Array<WikiFact['source_type']>;
+    /**
+     * When true, draft facts are dead ends for *discovered* nodes (not
+     * discovered, not traversed through). Does not gate the anchor.
+     * Resolves call → `WikiConfig.excludeDrafts` → false.
+     */
+    excludeDrafts?: boolean;
 }
 interface GraphNeighborhood {
     /** Anchor node first, then discovered neighbors ordered by depth ASC, then updated_at DESC. */
@@ -569,6 +586,48 @@ interface VectorRanker {
  * Fallback policy when rankBySimilarity rejects.
  */
 type VectorRankerFallback = 'js-cosine' | 'keyword' | 'empty' | 'throw';
+/** Severity is fixed per code (spec §4.2.6). */
+type WikiDiagnosticSeverity = 'info' | 'warn' | 'error';
+/**
+ * Closed for this release series, but new codes are added in minor versions:
+ * hosts must tolerate codes they do not recognize.
+ */
+type WikiDiagnosticCode = 'ingest_chunk_failed' | 'fact_rejected' | 'task_rejected' | 'fact_deduplicated' | 'edge_dropped' | 'embedding_failed' | 'hook_failed' | 'background_job_failed' | 'heal_skipped' | 'grounding_missing' | 'grounding_failed' | 'classification_low_confidence' | 'classification_invalid';
+/** The service run that emitted the diagnostic. */
+type WikiDiagnosticOperation = 'ingest' | 'upsertGraph' | 'librarian' | 'heal' | 'ontologyBackfill' | 'reembed' | 'importDump' | 'write';
+/** `'auto'` when a write threshold started the run (auto-librarian / auto-heal); `'call'` when the host did. */
+type WikiDiagnosticTrigger = 'call' | 'auto';
+/** Identifiers only — never titles, bodies, quotes, LLM output, provider messages, or hashes of content. */
+interface WikiDiagnosticDetail {
+    factId?: string;
+    sourceRef?: string;
+    chunkIndex?: number;
+    edgeType?: string;
+    /** Manifest slug of the edge source, when resolved. */
+    sourceNodeType?: string;
+    /** Manifest slug of the edge target, when resolved. */
+    targetNodeType?: string;
+    /** Position of a rejected item in the LLM response array. */
+    itemIndex?: number;
+    /** Machine-readable sub-reason, e.g. `'target_not_found'`. */
+    reason?: string;
+    /** Aggregated `ingest_chunk_failed` only; the first 20 failed chunk indexes. */
+    chunkIndexes?: number[];
+    /** Aggregated emissions only. */
+    count?: number;
+}
+interface WikiDiagnostic {
+    code: WikiDiagnosticCode;
+    severity: WikiDiagnosticSeverity;
+    operation: WikiDiagnosticOperation;
+    trigger: WikiDiagnosticTrigger;
+    entityId: string;
+    /** Epoch ms, sampled at emission. */
+    at: number;
+    /** Fixed template per code. Never contains content. */
+    message: string;
+    detail?: WikiDiagnosticDetail;
+}
 interface WikiOptions {
     config?: WikiConfig;
     llmProvider: LLMProvider;
@@ -634,6 +693,14 @@ interface WikiOptions {
      * NOT GDPR-safe for live indexes. Default false.
      */
     forceDeleteIgnoreRankerHook?: boolean;
+    /**
+     * Receives typed, content-free diagnostics for events core previously
+     * dropped silently or only logged (spec §4). Synchronous; a returned promise
+     * is ignored. A throwing or rejecting hook never affects the operation that
+     * emitted the diagnostic. Existing console output is unchanged whether or
+     * not this is set.
+     */
+    onDiagnostic?: (diagnostic: WikiDiagnostic) => void;
 }
 interface MemoryBundle {
     facts: WikiFact[];
@@ -892,6 +959,22 @@ declare class WikiInvalidReadOptions extends Error {
     readonly reason: string;
     constructor(field: string, reason: string);
 }
+/**
+ * Thrown by `promoteDraft` when no live draft with that id exists for the
+ * entity: missing, soft-deleted, owned by another entity, or not a draft.
+ * Contextless for the same reason as {@link WikiGraphNodeOwnershipConflict}.
+ * The `WIKI_` code keeps it clear of `extractSqliteCode`, so it passes through
+ * the serialized transaction wrapper unwrapped.
+ */
+declare class WikiDraftNotFound extends Error {
+    readonly code: "WIKI_DRAFT_NOT_FOUND";
+    constructor();
+}
+/** One page of `listDrafts`. `nextCursor` is opaque; pass it back unchanged. */
+interface DraftPage {
+    facts: WikiFact[];
+    nextCursor: string | null;
+}
 
 interface WikiOutboxEvent<T = unknown> {
     id: string;
@@ -1267,7 +1350,18 @@ declare class EntryRepository extends BaseRepository {
     }>>;
     trackAccess(ids: readonly string[], now: number, tx?: SQLiteAdapter): Promise<void>;
     getLegacyMigrationSQL(): string;
-    findRecentByEntityIds(entityIds: readonly string[], limit: number, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    findRecentByEntityIds(entityIds: readonly string[], limit: number, tx?: SQLiteAdapter, opts?: {
+        excludeDrafts?: boolean;
+    }): Promise<WikiFact[]>;
+    /** IDs of live draft facts for the given entities (spec §5.1). Callers pass ≤ 100 entity ids. */
+    findDraftIdsByEntityIds(entityIds: readonly string[], tx?: SQLiteAdapter): Promise<Set<string>>;
+    /** Live drafts for one entity, newest first, keyset-paged by (created_at, id). */
+    listDraftsByEntityId(entityId: string, limit: number, after: {
+        createdAt: number;
+        id: string;
+    } | null, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    /** True iff `entryId` is a live draft owned by `entityId`. */
+    isLiveDraft(entryId: string, entityId: string, tx?: SQLiteAdapter): Promise<boolean>;
     /**
      * Live untyped facts eligible for ontology backfill, oldest first.
      * Skips facts checked within the recheck cooldown (ontology_checked_at > recheckCutoff).
@@ -1640,6 +1734,34 @@ declare class JobManager {
     private _notifyStatusSubscribers;
 }
 
+declare function validateManifest(manifest: OntologyManifest): void;
+type EdgeDropReason = 'no_source_type' | 'invalid_shape' | 'type_not_in_manifest' | 'target_not_found' | 'target_type_mismatch';
+/** A dropped LLM-proposed edge. Slugs only — `target_title` is content and is never recorded. */
+interface EdgeDrop {
+    reason: EdgeDropReason;
+    /** Source fact id when known; null while validating before the fact has an id. */
+    sourceId: string | null;
+    edgeType: string | null;
+    sourceNodeType: string | null;
+    targetNodeType: string | null;
+}
+
+/** What a call site supplies; severity, message and timestamp are derived from `code`. */
+type WikiDiagnosticInput = Omit<WikiDiagnostic, 'severity' | 'message' | 'at'>;
+type DiagnosticTarget = Pick<WikiOptions, 'onDiagnostic'>;
+/**
+ * Operation-scoped buffer (spec §4.2.4): push while the operation's
+ * transaction is open, `flush` after it commits, `discard` (or simply drop the
+ * buffer) when the operation throws.
+ */
+declare class DiagnosticBuffer {
+    private items;
+    push(input: WikiDiagnosticInput): void;
+    get size(): number;
+    flush(options: DiagnosticTarget): void;
+    discard(): void;
+}
+
 interface NeighborhoodQueryOptions {
     maxDepth: number;
     direction: 'inbound' | 'outbound' | 'both';
@@ -1647,6 +1769,14 @@ interface NeighborhoodQueryOptions {
     minConfidence: 'certain' | 'inferred' | 'tentative';
     excludeSourceTypes: string[];
     maxNodes: number;
+    /**
+     * When true, draft facts are dead-ends for *discovered* nodes — the recursive
+     * walk will not step onto a draft, and will not step *past* one either, since
+     * a draft's neighbours are unreachable through it. The anchor node is exempt
+     * (it is validated up-front and never gated by this flag), so callers can
+     * intentionally start from a draft. Default false (drafts visible).
+     */
+    excludeDrafts?: boolean;
 }
 declare class EdgeRepository extends BaseRepository {
     /**
@@ -1690,6 +1820,10 @@ type EmbedFactResult = {
     ok: false;
     kind: EmbedFailureKind;
 };
+interface EmbedDiagnosticContext {
+    operation: WikiDiagnosticOperation;
+    trigger: WikiDiagnosticTrigger;
+}
 declare class EmbeddingService {
     private db;
     private options;
@@ -1732,7 +1866,10 @@ declare class EmbeddingService {
         title: string;
         body: string;
         tags: string | string[];
-    }): Promise<EmbedFactResult>;
+    }, ctx?: EmbedDiagnosticContext): Promise<EmbedFactResult>;
+    private reportEmbed;
+    /** For callers that invoke `notifyEmbeddingPersisted` directly and catch its failure. */
+    reportHookFailed(ctx: EmbedDiagnosticContext, entityId: string, factId: string): void;
     /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
     private markFailure;
     /**
@@ -1746,7 +1883,7 @@ declare class EmbeddingService {
         title: string;
         body: string;
         tags: string | string[];
-    }): Promise<boolean>;
+    }, ctx?: EmbedDiagnosticContext): Promise<boolean>;
     notifyEmbeddingPersisted(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
     notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
 }
@@ -1776,6 +1913,7 @@ declare class OntologyService {
     validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest, opts?: {
         strict?: boolean;
         entityId?: string;
+        drops?: EdgeDrop[];
     }): {
         okf_type: string | null;
         edges: ExtractedFactEdge[];
@@ -1787,7 +1925,7 @@ declare class OntologyService {
      * writes inside their own transaction (e.g. `IngestionService.ingestDocument`
      * when delegating to `upsertGraphCore`).
      */
-    resolveEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, now: number): WikiEdge[];
+    resolveEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, now: number, drops?: EdgeDrop[]): WikiEdge[];
     /**
      * Backwards-compatible wrapper: resolves edges via {@link resolveEdges},
      * then persists each via `edgeRepo.addIgnoreDuplicate` in the supplied
@@ -1795,7 +1933,7 @@ declare class OntologyService {
      * want self-contained edge persistence (e.g. MaintenanceService heal /
      * backfill callers that do not have a separate edge-write step).
      */
-    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number): Promise<number>;
+    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number, drops?: EdgeDrop[]): Promise<number>;
 }
 
 declare class PromptService {
@@ -1943,6 +2081,10 @@ declare class IngestionService {
         }[];
     }, tx: SQLiteAdapter, opts?: {
         strict?: boolean;
+        diag?: {
+            buffer: DiagnosticBuffer;
+            operation: 'ingest' | 'upsertGraph';
+        };
     }): Promise<{
         nodesWritten: number;
         edgesWritten: number;
@@ -2189,7 +2331,7 @@ declare class MaintenanceService {
      */
     private forgetDryRun;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
-    doRunLibrarian(entityId: string, promptOverride?: string): Promise<void>;
+    doRunLibrarian(entityId: string, promptOverride?: string, trigger?: WikiDiagnosticTrigger): Promise<void>;
     /**
      * Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook.
      *
@@ -2201,6 +2343,7 @@ declare class MaintenanceService {
         promptOverride?: string;
         batchSize?: number;
         bodyTruncationChars?: number;
+        trigger?: WikiDiagnosticTrigger;
     }): Promise<HealResult>;
     /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
     doRunOntologyBackfill(entityId: string, options?: {
@@ -2283,6 +2426,7 @@ declare class RetrievalService {
      * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
      */
     private _tieBreakSort;
+    private _withoutDrafts;
     /**
      * Comparator for score + deterministic tie-break fields.
      * Negative return means "a ranks ahead of b" for descending score order.
@@ -2319,6 +2463,7 @@ declare class WriteService {
      * {@link write}) so a partial pass retries on the next write.
      */
     private maybeRunHeal;
+    private reportBackgroundFailure;
 }
 
 /**
@@ -2695,6 +2840,25 @@ declare class WikiMemory {
     }>): Promise<void>;
     /** Set a fact's OKF v0.2 lifecycle status. Does NOT touch `updated_at`. */
     setLifecycleStatus(entryId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    /**
+     * 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.
+     */
+    listDrafts(entityId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<DraftPage>;
+    /**
+     * 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.
+     */
+    promoteDraft(entryId: string, entityId: string, reviewer: {
+        by: string;
+    }): Promise<void>;
     /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
     setStaleAfter(entryId: string, entityId: string, date: number | null): Promise<void>;
     /** Set a fact's generated_by actor string. Does NOT touch `updated_at`. */
@@ -2713,4 +2877,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiGraphNodeOwnershipConflict as $, type ReembedResult as A, type VectorRankerFallback as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerRankArgs as J, type VectorRankerSemanticResult as K, type LLMProvider as L, type MemoryBundle as M, WikiBusyError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiBusyOperation as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiCheckpoint as T, type WikiConfig as U, type VectorRanker as V, type WikiOptions as W, WikiDuplicateHashError as X, type WikiEdge as Y, type WikiEvent as Z, type WikiFact as _, type MemoryDump as a, WikiIngestEmptyError as a0, WikiInvalidReadOptions as a1, type WikiMemoryTestAccess as a2, type WikiOutboxEvent as a3, WikiParseError as a4, WikiSourceRefHashCollision as a5, WikiStrictOntologyViolation as a6, type WikiTask as a7, WikiTransactionError as a8, EmbeddingService as a9, ImportExportService as aa, IngestionService as ab, JobManager as ac, MaintenanceService as ad, RetrievalService as ae, SearchService as af, WriteService as ag, type FormattedMemoryDump as b, WikiMemory as c, type EmbedFailureKind as d, type EmbeddingMarkerKind as e, type EntityStatus as f, type ExtractedFact as g, type ExtractedFactEdge as h, type ExtractedFactWithOntology as i, type ExtractedTask as j, type GraphTraversalOptions as k, HEAL_RECHECK_MS as l, HOOK_TIMEOUT_MARKER as m, type HealResult as n, ONTOLOGY_BACKFILL_BATCH_SIZE as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyMode as u, type OntologyNodeType as v, type OntologyPromptContext as w, type OntologyUpdates as x, PromptService as y, PrunePartialFailureError as z };
+export { type WikiDiagnosticOperation as $, PrunePartialFailureError as A, type ReembedResult as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerFallback as J, type VectorRankerRankArgs as K, type LLMProvider as L, type MemoryBundle as M, type VectorRankerSemanticResult as N, ONTOLOGY_BACKFILL_BATCH_SIZE as O, type PromptOverrides as P, WikiBusyError as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiBusyOperation as T, type WikiCheckpoint as U, type VectorRanker as V, type WikiOptions as W, type WikiConfig as X, type WikiDiagnostic as Y, type WikiDiagnosticCode as Z, type WikiDiagnosticDetail as _, type MemoryDump as a, type WikiDiagnosticSeverity as a0, type WikiDiagnosticTrigger as a1, WikiDraftNotFound as a2, WikiDuplicateHashError as a3, type WikiEdge as a4, type WikiEvent as a5, type WikiFact as a6, WikiGraphNodeOwnershipConflict as a7, WikiIngestEmptyError as a8, WikiInvalidReadOptions as a9, type WikiMemoryTestAccess as aa, type WikiOutboxEvent as ab, WikiParseError as ac, WikiSourceRefHashCollision as ad, WikiStrictOntologyViolation as ae, type WikiTask as af, WikiTransactionError as ag, validateManifest as ah, EmbeddingService as ai, ImportExportService as aj, IngestionService as ak, JobManager as al, MaintenanceService as am, RetrievalService as an, SearchService as ao, WriteService as ap, type FormattedMemoryDump as b, WikiMemory as c, type DraftPage as d, type EmbedFailureKind as e, type EmbeddingMarkerKind as f, type EntityStatus as g, type ExtractedFact as h, type ExtractedFactEdge as i, type ExtractedFactWithOntology as j, type ExtractedTask as k, type GraphTraversalOptions as l, HEAL_RECHECK_MS as m, HOOK_TIMEOUT_MARKER as n, type HealResult as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyManifest as u, type OntologyMode as v, type OntologyNodeType as w, type OntologyPromptContext as x, type OntologyUpdates as y, PromptService as z };

package/dist/{testing-DYeMd9d1.d.ts → testing-Dmh1kfkd.d.ts}

@@ -269,6 +269,11 @@ interface WikiConfig {
     traversalDirection?: 'inbound' | 'outbound' | 'both';
     /** Default source_type dead-end list for discovered traversal nodes. Default []. */
     excludeSourceTypes?: Array<WikiFact['source_type']>;
+    /**
+     * Engine default for `ReadOptions.excludeDrafts` and
+     * `GraphTraversalOptions.excludeDrafts`. Default false (drafts visible).
+     */
+    excludeDrafts?: boolean;
 }
 interface ReadOptions {
     maxResults?: number;
@@ -309,6 +314,12 @@ interface ReadOptions {
      * by `tierWeights: 0`, or a floor keyed to an entity not in `entityId`.
      */
     tierFloors?: Record<string, number>;
+    /**
+     * When true, facts whose `lifecycle_status` is `'draft'` are excluded before
+     * `maxResults`, `tierFloors` and every other cut, on every read path.
+     * Resolves call → `WikiConfig.excludeDrafts` → false.
+     */
+    excludeDrafts?: boolean;
 }
 interface WikiFact {
     id: string;
@@ -451,6 +462,12 @@ interface GraphTraversalOptions {
     minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
     /** source_type values to dead-end on for *discovered* nodes. Does not gate the anchor. Default []. */
     excludeSourceTypes?: Array<WikiFact['source_type']>;
+    /**
+     * When true, draft facts are dead ends for *discovered* nodes (not
+     * discovered, not traversed through). Does not gate the anchor.
+     * Resolves call → `WikiConfig.excludeDrafts` → false.
+     */
+    excludeDrafts?: boolean;
 }
 interface GraphNeighborhood {
     /** Anchor node first, then discovered neighbors ordered by depth ASC, then updated_at DESC. */
@@ -569,6 +586,48 @@ interface VectorRanker {
  * Fallback policy when rankBySimilarity rejects.
  */
 type VectorRankerFallback = 'js-cosine' | 'keyword' | 'empty' | 'throw';
+/** Severity is fixed per code (spec §4.2.6). */
+type WikiDiagnosticSeverity = 'info' | 'warn' | 'error';
+/**
+ * Closed for this release series, but new codes are added in minor versions:
+ * hosts must tolerate codes they do not recognize.
+ */
+type WikiDiagnosticCode = 'ingest_chunk_failed' | 'fact_rejected' | 'task_rejected' | 'fact_deduplicated' | 'edge_dropped' | 'embedding_failed' | 'hook_failed' | 'background_job_failed' | 'heal_skipped' | 'grounding_missing' | 'grounding_failed' | 'classification_low_confidence' | 'classification_invalid';
+/** The service run that emitted the diagnostic. */
+type WikiDiagnosticOperation = 'ingest' | 'upsertGraph' | 'librarian' | 'heal' | 'ontologyBackfill' | 'reembed' | 'importDump' | 'write';
+/** `'auto'` when a write threshold started the run (auto-librarian / auto-heal); `'call'` when the host did. */
+type WikiDiagnosticTrigger = 'call' | 'auto';
+/** Identifiers only — never titles, bodies, quotes, LLM output, provider messages, or hashes of content. */
+interface WikiDiagnosticDetail {
+    factId?: string;
+    sourceRef?: string;
+    chunkIndex?: number;
+    edgeType?: string;
+    /** Manifest slug of the edge source, when resolved. */
+    sourceNodeType?: string;
+    /** Manifest slug of the edge target, when resolved. */
+    targetNodeType?: string;
+    /** Position of a rejected item in the LLM response array. */
+    itemIndex?: number;
+    /** Machine-readable sub-reason, e.g. `'target_not_found'`. */
+    reason?: string;
+    /** Aggregated `ingest_chunk_failed` only; the first 20 failed chunk indexes. */
+    chunkIndexes?: number[];
+    /** Aggregated emissions only. */
+    count?: number;
+}
+interface WikiDiagnostic {
+    code: WikiDiagnosticCode;
+    severity: WikiDiagnosticSeverity;
+    operation: WikiDiagnosticOperation;
+    trigger: WikiDiagnosticTrigger;
+    entityId: string;
+    /** Epoch ms, sampled at emission. */
+    at: number;
+    /** Fixed template per code. Never contains content. */
+    message: string;
+    detail?: WikiDiagnosticDetail;
+}
 interface WikiOptions {
     config?: WikiConfig;
     llmProvider: LLMProvider;
@@ -634,6 +693,14 @@ interface WikiOptions {
      * NOT GDPR-safe for live indexes. Default false.
      */
     forceDeleteIgnoreRankerHook?: boolean;
+    /**
+     * Receives typed, content-free diagnostics for events core previously
+     * dropped silently or only logged (spec §4). Synchronous; a returned promise
+     * is ignored. A throwing or rejecting hook never affects the operation that
+     * emitted the diagnostic. Existing console output is unchanged whether or
+     * not this is set.
+     */
+    onDiagnostic?: (diagnostic: WikiDiagnostic) => void;
 }
 interface MemoryBundle {
     facts: WikiFact[];
@@ -892,6 +959,22 @@ declare class WikiInvalidReadOptions extends Error {
     readonly reason: string;
     constructor(field: string, reason: string);
 }
+/**
+ * Thrown by `promoteDraft` when no live draft with that id exists for the
+ * entity: missing, soft-deleted, owned by another entity, or not a draft.
+ * Contextless for the same reason as {@link WikiGraphNodeOwnershipConflict}.
+ * The `WIKI_` code keeps it clear of `extractSqliteCode`, so it passes through
+ * the serialized transaction wrapper unwrapped.
+ */
+declare class WikiDraftNotFound extends Error {
+    readonly code: "WIKI_DRAFT_NOT_FOUND";
+    constructor();
+}
+/** One page of `listDrafts`. `nextCursor` is opaque; pass it back unchanged. */
+interface DraftPage {
+    facts: WikiFact[];
+    nextCursor: string | null;
+}
 
 interface WikiOutboxEvent<T = unknown> {
     id: string;
@@ -1267,7 +1350,18 @@ declare class EntryRepository extends BaseRepository {
     }>>;
     trackAccess(ids: readonly string[], now: number, tx?: SQLiteAdapter): Promise<void>;
     getLegacyMigrationSQL(): string;
-    findRecentByEntityIds(entityIds: readonly string[], limit: number, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    findRecentByEntityIds(entityIds: readonly string[], limit: number, tx?: SQLiteAdapter, opts?: {
+        excludeDrafts?: boolean;
+    }): Promise<WikiFact[]>;
+    /** IDs of live draft facts for the given entities (spec §5.1). Callers pass ≤ 100 entity ids. */
+    findDraftIdsByEntityIds(entityIds: readonly string[], tx?: SQLiteAdapter): Promise<Set<string>>;
+    /** Live drafts for one entity, newest first, keyset-paged by (created_at, id). */
+    listDraftsByEntityId(entityId: string, limit: number, after: {
+        createdAt: number;
+        id: string;
+    } | null, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    /** True iff `entryId` is a live draft owned by `entityId`. */
+    isLiveDraft(entryId: string, entityId: string, tx?: SQLiteAdapter): Promise<boolean>;
     /**
      * Live untyped facts eligible for ontology backfill, oldest first.
      * Skips facts checked within the recheck cooldown (ontology_checked_at > recheckCutoff).
@@ -1640,6 +1734,34 @@ declare class JobManager {
     private _notifyStatusSubscribers;
 }
 
+declare function validateManifest(manifest: OntologyManifest): void;
+type EdgeDropReason = 'no_source_type' | 'invalid_shape' | 'type_not_in_manifest' | 'target_not_found' | 'target_type_mismatch';
+/** A dropped LLM-proposed edge. Slugs only — `target_title` is content and is never recorded. */
+interface EdgeDrop {
+    reason: EdgeDropReason;
+    /** Source fact id when known; null while validating before the fact has an id. */
+    sourceId: string | null;
+    edgeType: string | null;
+    sourceNodeType: string | null;
+    targetNodeType: string | null;
+}
+
+/** What a call site supplies; severity, message and timestamp are derived from `code`. */
+type WikiDiagnosticInput = Omit<WikiDiagnostic, 'severity' | 'message' | 'at'>;
+type DiagnosticTarget = Pick<WikiOptions, 'onDiagnostic'>;
+/**
+ * Operation-scoped buffer (spec §4.2.4): push while the operation's
+ * transaction is open, `flush` after it commits, `discard` (or simply drop the
+ * buffer) when the operation throws.
+ */
+declare class DiagnosticBuffer {
+    private items;
+    push(input: WikiDiagnosticInput): void;
+    get size(): number;
+    flush(options: DiagnosticTarget): void;
+    discard(): void;
+}
+
 interface NeighborhoodQueryOptions {
     maxDepth: number;
     direction: 'inbound' | 'outbound' | 'both';
@@ -1647,6 +1769,14 @@ interface NeighborhoodQueryOptions {
     minConfidence: 'certain' | 'inferred' | 'tentative';
     excludeSourceTypes: string[];
     maxNodes: number;
+    /**
+     * When true, draft facts are dead-ends for *discovered* nodes — the recursive
+     * walk will not step onto a draft, and will not step *past* one either, since
+     * a draft's neighbours are unreachable through it. The anchor node is exempt
+     * (it is validated up-front and never gated by this flag), so callers can
+     * intentionally start from a draft. Default false (drafts visible).
+     */
+    excludeDrafts?: boolean;
 }
 declare class EdgeRepository extends BaseRepository {
     /**
@@ -1690,6 +1820,10 @@ type EmbedFactResult = {
     ok: false;
     kind: EmbedFailureKind;
 };
+interface EmbedDiagnosticContext {
+    operation: WikiDiagnosticOperation;
+    trigger: WikiDiagnosticTrigger;
+}
 declare class EmbeddingService {
     private db;
     private options;
@@ -1732,7 +1866,10 @@ declare class EmbeddingService {
         title: string;
         body: string;
         tags: string | string[];
-    }): Promise<EmbedFactResult>;
+    }, ctx?: EmbedDiagnosticContext): Promise<EmbedFactResult>;
+    private reportEmbed;
+    /** For callers that invoke `notifyEmbeddingPersisted` directly and catch its failure. */
+    reportHookFailed(ctx: EmbedDiagnosticContext, entityId: string, factId: string): void;
     /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
     private markFailure;
     /**
@@ -1746,7 +1883,7 @@ declare class EmbeddingService {
         title: string;
         body: string;
         tags: string | string[];
-    }): Promise<boolean>;
+    }, ctx?: EmbedDiagnosticContext): Promise<boolean>;
     notifyEmbeddingPersisted(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
     notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
 }
@@ -1776,6 +1913,7 @@ declare class OntologyService {
     validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest, opts?: {
         strict?: boolean;
         entityId?: string;
+        drops?: EdgeDrop[];
     }): {
         okf_type: string | null;
         edges: ExtractedFactEdge[];
@@ -1787,7 +1925,7 @@ declare class OntologyService {
      * writes inside their own transaction (e.g. `IngestionService.ingestDocument`
      * when delegating to `upsertGraphCore`).
      */
-    resolveEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, now: number): WikiEdge[];
+    resolveEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, now: number, drops?: EdgeDrop[]): WikiEdge[];
     /**
      * Backwards-compatible wrapper: resolves edges via {@link resolveEdges},
      * then persists each via `edgeRepo.addIgnoreDuplicate` in the supplied
@@ -1795,7 +1933,7 @@ declare class OntologyService {
      * want self-contained edge persistence (e.g. MaintenanceService heal /
      * backfill callers that do not have a separate edge-write step).
      */
-    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number): Promise<number>;
+    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number, drops?: EdgeDrop[]): Promise<number>;
 }
 
 declare class PromptService {
@@ -1943,6 +2081,10 @@ declare class IngestionService {
         }[];
     }, tx: SQLiteAdapter, opts?: {
         strict?: boolean;
+        diag?: {
+            buffer: DiagnosticBuffer;
+            operation: 'ingest' | 'upsertGraph';
+        };
     }): Promise<{
         nodesWritten: number;
         edgesWritten: number;
@@ -2189,7 +2331,7 @@ declare class MaintenanceService {
      */
     private forgetDryRun;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
-    doRunLibrarian(entityId: string, promptOverride?: string): Promise<void>;
+    doRunLibrarian(entityId: string, promptOverride?: string, trigger?: WikiDiagnosticTrigger): Promise<void>;
     /**
      * Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook.
      *
@@ -2201,6 +2343,7 @@ declare class MaintenanceService {
         promptOverride?: string;
         batchSize?: number;
         bodyTruncationChars?: number;
+        trigger?: WikiDiagnosticTrigger;
     }): Promise<HealResult>;
     /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
     doRunOntologyBackfill(entityId: string, options?: {
@@ -2283,6 +2426,7 @@ declare class RetrievalService {
      * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
      */
     private _tieBreakSort;
+    private _withoutDrafts;
     /**
      * Comparator for score + deterministic tie-break fields.
      * Negative return means "a ranks ahead of b" for descending score order.
@@ -2319,6 +2463,7 @@ declare class WriteService {
      * {@link write}) so a partial pass retries on the next write.
      */
     private maybeRunHeal;
+    private reportBackgroundFailure;
 }
 
 /**
@@ -2695,6 +2840,25 @@ declare class WikiMemory {
     }>): Promise<void>;
     /** Set a fact's OKF v0.2 lifecycle status. Does NOT touch `updated_at`. */
     setLifecycleStatus(entryId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    /**
+     * 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.
+     */
+    listDrafts(entityId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<DraftPage>;
+    /**
+     * 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.
+     */
+    promoteDraft(entryId: string, entityId: string, reviewer: {
+        by: string;
+    }): Promise<void>;
     /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
     setStaleAfter(entryId: string, entityId: string, date: number | null): Promise<void>;
     /** Set a fact's generated_by actor string. Does NOT touch `updated_at`. */
@@ -2713,4 +2877,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiGraphNodeOwnershipConflict as $, type ReembedResult as A, type VectorRankerFallback as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerRankArgs as J, type VectorRankerSemanticResult as K, type LLMProvider as L, type MemoryBundle as M, WikiBusyError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiBusyOperation as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiCheckpoint as T, type WikiConfig as U, type VectorRanker as V, type WikiOptions as W, WikiDuplicateHashError as X, type WikiEdge as Y, type WikiEvent as Z, type WikiFact as _, type MemoryDump as a, WikiIngestEmptyError as a0, WikiInvalidReadOptions as a1, type WikiMemoryTestAccess as a2, type WikiOutboxEvent as a3, WikiParseError as a4, WikiSourceRefHashCollision as a5, WikiStrictOntologyViolation as a6, type WikiTask as a7, WikiTransactionError as a8, EmbeddingService as a9, ImportExportService as aa, IngestionService as ab, JobManager as ac, MaintenanceService as ad, RetrievalService as ae, SearchService as af, WriteService as ag, type FormattedMemoryDump as b, WikiMemory as c, type EmbedFailureKind as d, type EmbeddingMarkerKind as e, type EntityStatus as f, type ExtractedFact as g, type ExtractedFactEdge as h, type ExtractedFactWithOntology as i, type ExtractedTask as j, type GraphTraversalOptions as k, HEAL_RECHECK_MS as l, HOOK_TIMEOUT_MARKER as m, type HealResult as n, ONTOLOGY_BACKFILL_BATCH_SIZE as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyMode as u, type OntologyNodeType as v, type OntologyPromptContext as w, type OntologyUpdates as x, PromptService as y, PrunePartialFailureError as z };
+export { type WikiDiagnosticOperation as $, PrunePartialFailureError as A, type ReembedResult as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerFallback as J, type VectorRankerRankArgs as K, type LLMProvider as L, type MemoryBundle as M, type VectorRankerSemanticResult as N, ONTOLOGY_BACKFILL_BATCH_SIZE as O, type PromptOverrides as P, WikiBusyError as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiBusyOperation as T, type WikiCheckpoint as U, type VectorRanker as V, type WikiOptions as W, type WikiConfig as X, type WikiDiagnostic as Y, type WikiDiagnosticCode as Z, type WikiDiagnosticDetail as _, type MemoryDump as a, type WikiDiagnosticSeverity as a0, type WikiDiagnosticTrigger as a1, WikiDraftNotFound as a2, WikiDuplicateHashError as a3, type WikiEdge as a4, type WikiEvent as a5, type WikiFact as a6, WikiGraphNodeOwnershipConflict as a7, WikiIngestEmptyError as a8, WikiInvalidReadOptions as a9, type WikiMemoryTestAccess as aa, type WikiOutboxEvent as ab, WikiParseError as ac, WikiSourceRefHashCollision as ad, WikiStrictOntologyViolation as ae, type WikiTask as af, WikiTransactionError as ag, validateManifest as ah, EmbeddingService as ai, ImportExportService as aj, IngestionService as ak, JobManager as al, MaintenanceService as am, RetrievalService as an, SearchService as ao, WriteService as ap, type FormattedMemoryDump as b, WikiMemory as c, type DraftPage as d, type EmbedFailureKind as e, type EmbeddingMarkerKind as f, type EntityStatus as g, type ExtractedFact as h, type ExtractedFactEdge as i, type ExtractedFactWithOntology as j, type ExtractedTask as k, type GraphTraversalOptions as l, HEAL_RECHECK_MS as m, HOOK_TIMEOUT_MARKER as n, type HealResult as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyManifest as u, type OntologyMode as v, type OntologyNodeType as w, type OntologyPromptContext as x, type OntologyUpdates as y, PromptService as z };

package/dist/testing.d.mts

@@ -1,3 +1,3 @@
-export { a9 as EmbeddingService, aa as ImportExportService, ab as IngestionService, ac as JobManager, ac as JobManagerType, ad as MaintenanceService, ae as RetrievalService, af as SearchService, af as SearchServiceType, a2 as WikiMemoryTestAccess, ag as WriteService } from './testing-DYeMd9d1.mjs';
+export { ai as EmbeddingService, aj as ImportExportService, ak as IngestionService, al as JobManager, al as JobManagerType, am as MaintenanceService, an as RetrievalService, ao as SearchService, ao as SearchServiceType, aa as WikiMemoryTestAccess, ap as WriteService } from './testing-Dmh1kfkd.mjs';
 import '@equationalapplications/core-okf';
 import 'minisearch';