@equationalapplications/core-llm-wiki 7.7.7 → 7.9.0

package/dist/{testing-BIFNLUva.d.ts → testing-Kb1uVj1E.d.ts}

@@ -214,6 +214,10 @@ interface HealResult {
     remaining: number;
     /** Heal candidates inside the recheck cooldown. */
     deferred: number;
+    /** Present when a token budget stopped the pass early (spec §10.5). Unattempted candidates stay eligible. */
+    budgetStop?: {
+        requiredEstimate: number;
+    };
 }
 /**
  * Opt-in evidence check for LLM-authored facts (spec §6). Default off: 7.x
@@ -232,6 +236,19 @@ interface GroundingConfig {
     /** Characters retained per quote. Default 300. */
     maxEvidenceChars?: number;
 }
+interface LibrarianGateConfig {
+    /** Neighbours fetched per candidate. Default 5. */
+    k?: number;
+    /** Cosine at or above which (with title Jaccard ≥ FUZZY_THRESHOLD) a candidate is a duplicate. Default 0.89 (calibrated against the 30 supersession scenarios). */
+    dupThreshold?: number;
+    /** Best-neighbour cosine below which a candidate is novel. Default 0.30 (calibrated against the 30 supersession scenarios). */
+    novelThreshold?: number;
+}
+/** `'legacy'` is the 7.x add-only librarian. `'ops'` is the spec §5.1 / §5.3 dispatcher. */
+interface LibrarianConfig {
+    strategy?: 'legacy' | 'ops';
+    gate?: LibrarianGateConfig;
+}
 interface WikiConfig {
     /**
      * Prefix applied to every SQL table/index/trigger name. Must match
@@ -245,6 +262,12 @@ interface WikiConfig {
     maxFtsResults?: number;
     pruneEventsAfter?: number;
     pruneRetainSoftDeletedFor?: number;
+    /**
+     * Days after `valid_to` before `runPrune` soft-deletes an expired or
+     * superseded fact (the soft-delete retention then hard-deletes it).
+     * Default null = keep history forever.
+     */
+    pruneSupersededAfter?: number | null;
     autoLibrarianThreshold?: number;
     autoHealThreshold?: number;
     orphanAfterDays?: number | null;
@@ -305,6 +328,21 @@ interface WikiConfig {
     excludeDrafts?: boolean;
     /** Evidence check for LLM-authored facts (spec §6). Default off. */
     grounding?: GroundingConfig;
+    /** Emit an `llm_usage` diagnostic after every LLM text call. Default false. */
+    reportLlmUsage?: boolean;
+    /** Librarian strategy selection (spec 2026-09-29 §5.1). Default `{ strategy: 'legacy' }`. */
+    librarian?: LibrarianConfig;
+    /**
+     * `'auto'` (default): write() starts librarian/heal in the background when
+     * thresholds are crossed. `'deferred'`: write() only records the event; the
+     * host runs `runPendingMaintenance()` (spec 2026-09-29 §6). Pair with
+     * `librarian: { strategy: 'ops' }`: the legacy strategy reads only the
+     * newest 50 events per pass and advances the watermark past them, so a
+     * deferred backlog larger than that is never extracted.
+     */
+    maintenance?: 'auto' | 'deferred';
+    /** `'auto'` mode only: also trigger the librarian when pending event text reaches ~this many tokens (chars/4). */
+    autoLibrarianTokenThreshold?: number;
 }
 interface ReadOptions {
     maxResults?: number;
@@ -351,6 +389,18 @@ interface ReadOptions {
      * Resolves call → `WikiConfig.excludeDrafts` → false.
      */
     excludeDrafts?: boolean;
+    /**
+     * Valid-time snapshot (epoch ms): return facts live at this instant using
+     * current knowledge (spec §4.2). Omitted ⇒ current facts only.
+     * Throws `WikiInvalidReadOptions('asOf', …)` when not a finite number >= 0.
+     */
+    asOf?: number;
+    /**
+     * Pack facts into roughly this many tokens (chars/4 estimate), most valuable
+     * per token first; the top fact is always kept (truncated if needed).
+     * Tasks and events are not affected. Spec 2026-09-29 §7.1.
+     */
+    tokenBudget?: number;
 }
 interface WikiFact {
     id: string;
@@ -425,6 +475,14 @@ interface WikiFact {
      * `mapRowToFact` / `mapRowToTask`.
      */
     trustTier?: 'unverified' | 'machine-confirmed' | 'human-reviewed';
+    /** Epoch ms the fact became true in the world. Absent ⇒ since `created_at`. */
+    valid_from?: number | null;
+    /** Epoch ms the fact stopped being true (exclusive). Absent ⇒ open-ended. */
+    valid_to?: number | null;
+    /** Id of the fact that replaced this one. Audit / `history()` only; reads never filter on it. */
+    superseded_by?: string | null;
+    /** Epoch ms the supersession was recorded (transaction time). Audit only. */
+    superseded_at?: number | null;
 }
 interface WikiTask {
     id: string;
@@ -467,6 +525,8 @@ interface WikiEvent {
     summary: string;
     related_entry_id?: string | null;
     created_at: number;
+    /** Real-world time of the event (epoch ms). `created_at` stays ingestion time and remains the ordering key. */
+    occurred_at?: number | null;
 }
 interface WikiEdge {
     id: string;
@@ -499,6 +559,10 @@ interface GraphTraversalOptions {
      * Resolves call → `WikiConfig.excludeDrafts` → false.
      */
     excludeDrafts?: boolean;
+    /** Valid-time snapshot for traversal (epoch ms); an edge is walkable only when both endpoints are live at this instant. Omitted ⇒ now. */
+    asOf?: number;
+    /** Pack nodes (anchor first, then BFS order) into roughly this many tokens; edges to dropped nodes are removed. */
+    tokenBudget?: number;
 }
 interface GraphNeighborhood {
     /** Anchor node first, then discovered neighbors ordered by depth ASC, then updated_at DESC. */
@@ -538,6 +602,22 @@ interface LLMProvider {
         systemPrompt: string;
         userPrompt: string;
     }) => Promise<string>;
+    /**
+     * Optional. When present, core calls this instead of `generateText` and
+     * meters the reported usage (spec 2026-09-29 §6.3). Called with the provider
+     * as `this`. Omit `usage` (or return malformed numbers) to fall back to the
+     * chars/4 estimate.
+     */
+    generateTextWithUsage?: (params: {
+        systemPrompt: string;
+        userPrompt: string;
+    }) => Promise<{
+        text: string;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>;
     /**
      * Optional. When provided, enables semantic similarity search in `read()`.
      * Must return a stable-dimension float array for any input text.
@@ -672,9 +752,9 @@ 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';
+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' | 'llm_usage' | 'librarian_gate' | 'librarian_op_rejected' | 'contradicts_document' | 'resolve_failed' | 'read_budget' | 'event_retention_held';
 /** The service run that emitted the diagnostic. */
-type WikiDiagnosticOperation = 'ingest' | 'upsertGraph' | 'librarian' | 'heal' | 'ontologyBackfill' | 'reembed' | 'importDump' | 'write';
+type WikiDiagnosticOperation = 'ingest' | 'upsertGraph' | 'librarian' | 'heal' | 'ontologyBackfill' | 'reembed' | 'importDump' | 'write' | 'supersede' | 'read' | 'prune';
 /** `'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. */
@@ -695,6 +775,24 @@ interface WikiDiagnosticDetail {
     chunkIndexes?: number[];
     /** Aggregated emissions only. */
     count?: number;
+    /** `llm_usage` only. */
+    inputTokens?: number;
+    /** `llm_usage` only. */
+    outputTokens?: number;
+    /** `llm_usage` only: true when a figure is the chars/4 estimate. */
+    estimated?: boolean;
+    /** librarian_gate only. */
+    gateNoop?: number;
+    /** librarian_gate only. */
+    gateAdd?: number;
+    /** librarian_gate only. */
+    gateAmbiguous?: number;
+    /** read_budget only. */
+    candidates?: number;
+    /** read_budget only. */
+    packed?: number;
+    /** read_budget only. */
+    tokensUsed?: number;
 }
 interface WikiDiagnostic {
     code: WikiDiagnosticCode;
@@ -818,6 +916,8 @@ interface FormatContextOptions {
     includeTags?: boolean;
     includeEntityIds?: boolean;
     includeFactScores?: boolean;
+    /** Title + body only; overrides every include* flag. Default false. */
+    compact?: boolean;
     factWeights?: {
         confidence?: number;
         accessCount?: number;
@@ -1050,6 +1150,22 @@ declare class WikiDraftNotFound extends Error {
     readonly code: "WIKI_DRAFT_NOT_FOUND";
     constructor();
 }
+type WikiSupersedeReason = 'not_found' | 'already_superseded' | 'immutable_target' | 'cycle' | 'cross_entity';
+/** Thrown by `supersede()` (spec §4.3). Contextless like {@link WikiDraftNotFound}. */
+declare class WikiSupersedeError extends Error {
+    readonly code: "WIKI_SUPERSEDE_REJECTED";
+    readonly reason: WikiSupersedeReason;
+    constructor(reason: WikiSupersedeReason);
+}
+/** A new fact to create as the replacement, or the id of an existing fact. */
+type SupersedeReplacement = string | {
+    title: string;
+    body: string;
+    tags?: string[];
+    confidence?: WikiFact['confidence'];
+    source_type?: 'user_stated' | 'user_confirmed' | 'librarian_inferred';
+    valid_from?: number;
+};
 /** One page of `listDrafts`. `nextCursor` is opaque; pass it back unchanged. */
 interface DraftPage {
     facts: WikiFact[];
@@ -1092,6 +1208,62 @@ interface WikiInstructions {
     heal: string;
     ontologyBackfill: string;
 }
+type MaintenanceJob = 'librarian' | 'heal' | 'reembed';
+interface PendingMaintenance {
+    entityId: string;
+    /** Events after the librarian watermark. */
+    pendingEvents: number;
+    /** ceil(sum of pending event summary chars / 4). */
+    pendingTokensEstimate: number;
+    /** Same rule as auto-heal: events since the heal checkpoint >= autoHealThreshold. */
+    healDue: boolean;
+    /**
+     * Non-deleted facts (superseded history rows included, matching what
+     * `runReembed` sweeps) with no stored embedding that are still retryable.
+     * Always false without `embed`.
+     */
+    reembedPending: boolean;
+}
+interface RunPendingMaintenanceOptions {
+    /** Default: every entity with pending work. */
+    entityIds?: string[];
+    /** generateText tokens (provider-reported or chars/4). Omitted = unbounded. */
+    tokenBudget?: number;
+    /** Wall-clock milliseconds from the call. Checked between units; a unit in flight is never interrupted. */
+    deadlineMs?: number;
+    /** Default all three. */
+    jobs?: MaintenanceJob[];
+}
+type MaintenanceStopReason = {
+    reason: 'complete';
+} | {
+    reason: 'deadline';
+} | {
+    reason: 'budget_exhausted';
+} | {
+    reason: 'budget_too_small';
+    job: 'librarian' | 'heal';
+    entityId: string;
+    requiredEstimate: number;
+};
+interface EntityMaintenanceReport {
+    entityId: string;
+    librarianPasses: number;
+    factsWritten: number;
+    healPasses: number;
+    reembedded: boolean;
+    /** Set when a lock was held elsewhere; nothing ran for that job. */
+    busy?: MaintenanceJob[];
+}
+interface RunPendingMaintenanceResult {
+    perEntity: EntityMaintenanceReport[];
+    tokensUsed: number;
+    /** True when any usage figure was a chars/4 estimate. */
+    estimated: boolean;
+    /** null when no tokenBudget was given. */
+    remaining: number | null;
+    stoppedReason: MaintenanceStopReason;
+}
 
 interface WikiOutboxEvent<T = unknown> {
     id: string;
@@ -1147,6 +1319,36 @@ declare class OutboxRepository extends BaseRepository {
     acknowledge(ids: string[]): Promise<void>;
 }
 
+/**
+ * Single definition of fact liveness (spec 2026-09-29 §4.2). Every read path
+ * uses these so SQL and JS can never disagree.
+ *
+ * - 'asOf' — valid time using current knowledge: live at T when
+ *   COALESCE(valid_from, created_at) <= T < valid_to (valid_to NULL = open).
+ * - 'current' — live now per the row's own validity columns. A row with both
+ *   columns NULL is always current; created_at is deliberately ignored so
+ *   existing rows (and fixtures with arbitrary created_at) stay current.
+ */
+type LiveMode = 'current' | 'asOf';
+
+/** Subset of temporal columns that {@link EntryRepository.setTemporal} may write (spec 2026-09-29 §4.3). */
+type TemporalFields = {
+    valid_from?: number | null;
+    valid_to?: number | null;
+    superseded_by?: string | null;
+    superseded_at?: number | null;
+};
+/** Lightweight projection used by TemporalService for supersession chain walks. */
+type TemporalRow = {
+    id: string;
+    entity_id: string;
+    source_type: WikiFact['source_type'];
+    deleted_at: number | null;
+    created_at: number;
+    valid_from: number | null;
+    valid_to: number | null;
+    superseded_by: string | null;
+};
 type EntryRowMetadata = {
     id: string;
     entity_id: string;
@@ -1370,6 +1572,23 @@ declare class EntryRepository extends BaseRepository {
      * Used by MaintenanceService.doRunHeal().
      */
     softDeleteByIds(ids: string[], entityId: string, tx: SQLiteAdapter): Promise<void>;
+    /** Spec §4: write any subset of the four temporal columns. Absent key = untouched; null = clear. */
+    setTemporal(id: string, entityId: string, fields: TemporalFields, tx: SQLiteAdapter, opts?: {
+        outbox?: boolean;
+    }): Promise<number>;
+    findTemporalRow(id: string, tx?: SQLiteAdapter): Promise<TemporalRow | null>;
+    /**
+     * Ids of non-deleted facts NOT live at `t` (spec §4.2). In 'current' mode a
+     * row with both validity columns NULL is always live, so the query is
+     * restricted to rows that carry a validity column — served by the partial
+     * entries_temporal_idx.
+     */
+    findNonLiveIdsByEntityIds(entityIds: readonly string[], mode: LiveMode, t: number, tx?: SQLiteAdapter): Promise<Set<string>>;
+    findSupersessionChainIds(entityId: string, factId: string, maxDepth: number, tx?: SQLiteAdapter): Promise<{
+        predecessors: string[];
+        successors: string[];
+    }>;
+    findExpiredIds(entityId: string, cutoff: number, tx?: SQLiteAdapter): Promise<string[]>;
     /**
      * Bulk soft-delete all entries for an entity.
      * Stages DELETE outbox entries for each row in the same transaction.
@@ -1503,6 +1722,10 @@ declare class EntryRepository extends BaseRepository {
     getLegacyMigrationSQL(): string;
     findRecentByEntityIds(entityIds: readonly string[], limit: number, tx?: SQLiteAdapter, opts?: {
         excludeDrafts?: boolean;
+        live?: {
+            mode: LiveMode;
+            t: number;
+        };
     }): 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>>;
@@ -1577,6 +1800,13 @@ declare class EntryRepository extends BaseRepository {
         id: string;
         title: string;
     }>>;
+    /**
+     * Count of live facts for `entityId` with no stored embedding that are still
+     * retryable (`embedding_attempts < maxAttempts`). Backs the deferred
+     * maintenance pending report's `reembedPending` flag and the reembed job's
+     * entity selection (PR-C 2026-09-29).
+     */
+    countReembedPending(entityId: string, maxAttempts: number, tx?: SQLiteAdapter): Promise<number>;
 }
 
 /**
@@ -1622,6 +1852,15 @@ declare class SourceRefIndexRepository extends BaseRepository {
     findActiveByEntityAndHash(entityId: string, sourceHash: string, tx?: SQLiteAdapter): Promise<string | null>;
 }
 
+/**
+ * The op-based librarian's high-water mark on the `events` table. Stored
+ * alongside `memory_checkpoint` / `heal_checkpoint` so an entity's
+ * maintenance state stays in one row. See spec 2026-09-29 §4.1.
+ */
+type LibrarianWatermark = {
+    at: number;
+    id: string;
+};
 declare class MetadataRepository extends BaseRepository {
     getCheckpoint(entityId: string, tx: SQLiteAdapter): Promise<{
         memory?: number;
@@ -1632,6 +1871,17 @@ declare class MetadataRepository extends BaseRepository {
         heal?: number;
     }, tx: SQLiteAdapter): Promise<void>;
     deleteCheckpoint(entityId: string, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * Read the op-based librarian's high-water mark. Returns `null` when the
+     * entity has never had its watermark set.
+     */
+    getLibrarianWatermark(entityId: string, tx: SQLiteAdapter): Promise<LibrarianWatermark | null>;
+    /**
+     * Write the op-based librarian's high-water mark. Uses `ON CONFLICT`
+     * `DO UPDATE` so existing `memory_checkpoint` / `heal_checkpoint` rows
+     * are preserved verbatim.
+     */
+    setLibrarianWatermark(entityId: string, wm: LibrarianWatermark, tx: SQLiteAdapter): Promise<void>;
     getMeta(key: string, tx?: SQLiteAdapter): Promise<string | null>;
     setMeta(key: string, value: string, tx: SQLiteAdapter): Promise<void>;
     deleteMeta(key: string, tx?: SQLiteAdapter): Promise<void>;
@@ -1773,6 +2023,13 @@ declare class SearchService {
      * cannot index itself, such as upsertGraph inside a host transaction.
      */
     markStale(entityId: string): void;
+    /**
+     * Runs syncEntries(id, []) for each entity marked stale when this is called,
+     * so only those entities are rebuilt. Each rebuild still takes its own turn
+     * on the sync chain, and like syncEntries this never rejects. With nothing
+     * stale it resolves at once, without waiting on work already on the chain.
+     */
+    syncStale(): Promise<void>;
     /**
      * Clears the parsed vector cache. Useful for mid-loop flush guarantees
      * or memory pressure evictions.
@@ -1987,6 +2244,11 @@ interface NeighborhoodQueryOptions {
      * intentionally start from a draft. Default false (drafts visible).
      */
     excludeDrafts?: boolean;
+    /** Liveness gate for discovered nodes: 'current' (live now) or 'asOf' (valid time T). Always supplied by GraphTraversalService. */
+    live: {
+        mode: LiveMode;
+        t: number;
+    };
 }
 declare class EdgeRepository extends BaseRepository {
     /**
@@ -2077,6 +2339,40 @@ declare class EmbeddingService {
         body: string;
         tags: string | string[];
     }, ctx?: EmbedDiagnosticContext): Promise<EmbedFactResult>;
+    /**
+     * Compute half: build the embed text, call embed(), validate the result,
+     * mark any embed-time failure, and return the validated Float32 vector.
+     *
+     * Failure kinds: `no_provider`, `invalid_vector`, `float32_overflow`,
+     * `provider_error`. All embed-time failures are marked via `markFailure`;
+     * `no_provider` deliberately does not mark (spec §2.4).
+     *
+     * Storage errors are NOT possible here — that is `storeFactVector`'s domain.
+     */
+    embedTextForFact(fact: {
+        id: string;
+        entity_id: string;
+        title: string;
+        body: string;
+        tags: string | string[];
+    }, ctx?: EmbedDiagnosticContext, opts?: {
+        markFailures?: boolean;
+    }): Promise<{
+        ok: true;
+        vector: Float32Array;
+    } | {
+        ok: false;
+        kind: EmbedFailureKind;
+    }>;
+    /**
+     * Storage half: persist the computed vector to the entry row, then fire the
+     * `onEmbeddingPersisted` hook. Failure kinds: `storage_error` only — embed
+     * failures do not originate here, so they cannot be marked as such (spec §3.2, D3).
+     */
+    storeFactVector(fact: {
+        id: string;
+        entity_id: string;
+    }, float32Vector: Float32Array, ctx?: EmbedDiagnosticContext): Promise<EmbedFactResult>;
     private reportEmbed;
     /** For callers that invoke `notifyEmbeddingPersisted` directly and catch its failure. */
     reportHookFailed(ctx: EmbedDiagnosticContext, entityId: string, factId: string): void;
@@ -2161,6 +2457,12 @@ interface GroundingTrust {
     last_verified_by?: string;
 }
 
+type LabeledEvent = {
+    label: string;
+    event: WikiEvent;
+    at: number;
+};
+
 declare class PromptService {
     private globalOverrides?;
     private grounding;
@@ -2216,6 +2518,28 @@ declare class PromptService {
         systemPrompt: string;
         userPrompt: string;
     };
+    /** Ops extract (spec §5.2): events only — no existing facts. */
+    buildOpsExtractPrompt(events: LabeledEvent[], ontologyContext?: OntologyPromptContext | null): {
+        systemPrompt: string;
+        userPrompt: string;
+        groundingCorpus?: string[];
+    };
+    /** Ops resolve (spec §5.4): only each item's own neighbours. */
+    buildOpsResolvePrompt(items: Array<{
+        item: number;
+        candidate: {
+            title: string;
+            body: string;
+        };
+        existing: Array<{
+            ref: string;
+            title: string;
+            body: string;
+        }>;
+    }>): {
+        systemPrompt: string;
+        userPrompt: string;
+    };
     /**
      * The system prompt each writer would send, without hydrating data (spec
      * §8.3). `buildSystemPrompt` with no variables hydrates only ontology
@@ -2456,6 +2780,22 @@ declare class EventRepository extends BaseRepository {
     prune(entityId: string, cutoff: number): Promise<{
         changes: number;
     }>;
+    /**
+     * Watermark-guarded prune (spec 2026-09-29 competitive-memory §6): delete
+     * events at or before `cutoff` **and** at-or-before the librarian watermark.
+     * Events the librarian has not processed yet are retention-held, never
+     * deleted. `wm = null` (no watermark yet) deletes nothing.
+     * Used by runPrune under the deferred/ops strategies.
+     */
+    pruneThrough(entityId: string, cutoff: number, wm: LibrarianWatermark | null): Promise<{
+        changes: number;
+    }>;
+    /**
+     * Count events at or before `cutoff` that are after the watermark — the
+     * retention-held tail `pruneThrough` left in place. `wm = null` counts all
+     * events at or before `cutoff` (every one of them is held back).
+     */
+    countHeldBack(entityId: string, cutoff: number, wm: LibrarianWatermark | null): Promise<number>;
     /**
      * Return the total number of events stored for an entity.
      * `tx` is optional — pass an active transaction handle for atomic reads.
@@ -2466,6 +2806,105 @@ declare class EventRepository extends BaseRepository {
      * When limit is provided, fetches newest-first then reverses to preserve chronological order.
      */
     getByEntityId(entityId: string, limit?: number): Promise<WikiEvent[]>;
+    /**
+     * Return events for `entityId` strictly after the watermark `(at, id)` in
+     * chronological (ASC, id-ASC tie-break) order. Pass `wm = null` to read
+     * from the beginning of the entity's event log. `limit` caps the result.
+     *
+     * Used by the op-based librarian (PR-B) to enumerate its unprocessed tail.
+     */
+    getAfter(entityId: string, wm: LibrarianWatermark | null, limit?: number): Promise<WikiEvent[]>;
+    /**
+     * Count of events for `entityId` strictly after the watermark. Used as
+     * the op-based librarian's bounded batch size and by the deferred-maintenance
+     * pending report. Pass `wm = null` to count the entity's whole event log
+     * (no watermark yet) — mirrors `getAfter` / `sumSummaryCharsAfter`.
+     */
+    countAfter(entityId: string, wm: LibrarianWatermark | null): Promise<number>;
+    /**
+     * Return the event at a given chronological offset for `entityId` (0-based,
+     * oldest first). Used by MaintenanceService.seedLibrarianWatermark to anchor
+     * the watermark on a real row when a legacy DB first migrates to the
+     * op-based librarian. The offset is clamped and truncated to defend against
+     * hostile or fractional callers.
+     */
+    getAtOffset(entityId: string, offset: number, tx?: SQLiteAdapter): Promise<WikiEvent | null>;
+    /**
+     * Sum of `summary` lengths (in characters) for events for `entityId`
+     * strictly after the watermark. Pass `wm = null` to sum the entity's whole
+     * event log (no watermark yet). Used by the op-based librarian's token
+     * budget estimator (PR-B) and by the auto-trigger's pending-size check
+     * (PR-C). SQLite's `LENGTH` returns character count for UTF-8 text input.
+     */
+    sumSummaryCharsAfter(entityId: string, wm: LibrarianWatermark | null, tx?: SQLiteAdapter): Promise<number>;
+}
+
+interface UsageRecord {
+    inputTokens: number;
+    outputTokens: number;
+    /** True when either figure came from estimateTokens rather than the provider. */
+    estimated: boolean;
+}
+/** One budget shared by every LLM call in a maintenance run. */
+declare class UsageMeter {
+    readonly budget: number | undefined;
+    used: number;
+    estimated: boolean;
+    constructor(budget?: number);
+    get remaining(): number;
+    fits(estimate: number): boolean;
+    record(r: UsageRecord): void;
+}
+
+/**
+ * Librarian strategy seam (spec 2026-09-29 §5.1).
+ *
+ * The seam lets PR-B (ops librarian) plug in without `MaintenanceService`
+ * editing the body. The verbatim legacy move lives in `legacy.ts`; the
+ * dispatcher in `index.ts` is the only place that knows which strategies
+ * exist. New strategies register there.
+ *
+ * `LibrarianStrategy` is the contract every implementation satisfies. The
+ * pass is identified by its `(entityId, trigger, promptOverride?, meter?)`
+ * context; the strategy returns what it processed so the caller can
+ * advance checkpoints / watermarks.
+ */
+
+/** Per-pass inputs the caller decides; the strategy cannot derive these. */
+interface LibrarianContext {
+    entityId: string;
+    trigger: WikiDiagnosticTrigger;
+    promptOverride?: string;
+    /** Optional meter (Phase C budgeted maintenance). Legacy honors it:
+     * `callLlm` pre-flights the prompt estimate against it, usage is recorded
+     * on every call, and the pass returns `budgetStop` when the budget is
+     * exhausted (see `librarianBudget.test.ts`). */
+    meter?: UsageMeter;
+}
+/**
+ * Position in the event log a pass read through: the event's `created_at`
+ * (epoch ms) and its id. Callers advance checkpoints / watermarks with it.
+ */
+interface EventCursor {
+    at: number;
+    id: string;
+}
+/**
+ * What the strategy did. The shape is intentionally narrow: callers (lock
+ * wrapper, deferred scheduler) only need to know whether work happened and
+ * whether a budget error truncated it. PR-B adds its own watermark
+ * semantics; the legacy `processedThrough` is an {@link EventCursor} for the
+ * newest event the pass read (or null when there were no events).
+ */
+interface LibrarianResult {
+    /** Newest event the pass processed (epoch ms + id), or `null` if the event log was empty. */
+    processedThrough: EventCursor | null;
+    /** Number of facts actually written (excludes deduped, rejected, failed-validation). */
+    factsWritten: number;
+    /** Set only when `callLlm` raised `WikiBudgetExhausted`. */
+    budgetStop?: {
+        requiredEstimate: number;
+    };
 }
 
 declare const ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
@@ -2574,6 +3013,39 @@ declare class MaintenanceService {
     private forgetDryRun;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
     doRunLibrarian(entityId: string, promptOverride?: string, trigger?: WikiDiagnosticTrigger): Promise<void>;
+    /**
+     * Seam between the lock wrapper and the strategy dispatcher (spec 2026-09-29
+     * §5.1). Builds the strategy deps from `this` and dispatches via
+     * `runLibrarianStrategy` so PR-B can plug in `ops/` without touching this
+     * class. Returns the strategy's `LibrarianResult` so deferred/budgeted
+     * schedulers (PR-C) can advance watermarks; the existing void-returning
+     * `doRunLibrarian` discards it.
+     *
+     * Spec §10.3: one place advances the watermark, for every strategy, only
+     * after the pass resolved (its transaction committed) and never backwards.
+     * A budget-stopped pass wrote nothing and must not move the watermark.
+     */
+    runLibrarianPass(ctx: LibrarianContext): Promise<LibrarianResult>;
+    /**
+     * Strategy deps shared between legacy and ops librarians (spec §5.1). The
+     * ops strategy (PR-B Task 8) reads/anchors the watermark through these two
+     * hooks so the dispatcher itself never reaches into the metadata table —
+     * the watermark invariant (one place advances, never backwards) lives here.
+     */
+    private librarianDeps;
+    /**
+     * Persist `next` as the entity's librarian watermark when it is strictly
+     * newer than the stored value, under the (created_at, id) ordering used by
+     * the op-based librarian (spec §10.3). Never moves backwards.
+     */
+    private advanceLibrarianWatermark;
+    /**
+     * Spec §10.3: first ops pass on a legacy DB starts after what the count
+     * checkpoint already covered. No-op when a watermark already exists or the
+     * memory checkpoint is 0; otherwise anchor the watermark to the event at
+     * offset `min(memory_checkpoint, totalEvents) - 1`.
+     */
+    seedLibrarianWatermark(entityId: string): Promise<void>;
     /**
      * Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook.
      *
@@ -2586,6 +3058,7 @@ declare class MaintenanceService {
         batchSize?: number;
         bodyTruncationChars?: number;
         trigger?: WikiDiagnosticTrigger;
+        meter?: UsageMeter;
     }): Promise<HealResult>;
     /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
     doRunOntologyBackfill(entityId: string, options?: {
@@ -2632,6 +3105,43 @@ declare class MaintenanceService {
     private _sanitizeRankerError;
 }
 
+/**
+ * Read-side report for the deferred maintenance mode: which entities have
+ * pending work (librarian events behind the watermark, heal backlog, unembedded
+ * facts) without running anything. `run` executes the work (PR-C task 4).
+ */
+declare class MaintenanceScheduler {
+    private db;
+    private options;
+    private maintenanceService;
+    private metadataRepo;
+    private eventRepo;
+    private entryRepo;
+    private jobManager;
+    constructor(db: SQLiteAdapter, options: WikiOptions, maintenanceService: MaintenanceService, metadataRepo: MetadataRepository, eventRepo: EventRepository, entryRepo: EntryRepository, jobManager: JobManager);
+    /**
+     * Entities with **any** pending work only, sorted by `pendingEvents` desc
+     * then `entityId` asc. Token estimate is ceil(pending summary chars / 4),
+     * matching the auto-trigger's estimator (PR-B).
+     */
+    getPending(entityIds?: string[]): Promise<PendingMaintenance[]>;
+    /**
+     * Execute pending maintenance (spec §6.2): fair-share rounds of at most one
+     * unit per entity (librarian batch, else heal batch, else reembed), entities
+     * ordered by `getPending` (pendingEvents desc, id asc). Holds the same
+     * per-entity `JobManager` locks a manual run would; a busy entity is skipped
+     * and reported, never thrown. Nothing is still running when this resolves.
+     *
+     * Stop precedence (spec §10 items 3-6): `deadline` > `budget_exhausted` >
+     * `budget_too_small` > `complete`. `budget_too_small` means a job's smallest
+     * unit needs more than the WHOLE budget — that job is skipped this run and
+     * the run continues; `budget_exhausted` means a unit needs more than what
+     * REMAINS — the run stops. The token budget meters `generateText` calls
+     * only; embeddings are never metered.
+     */
+    run(opts?: RunPendingMaintenanceOptions): Promise<RunPendingMaintenanceResult>;
+}
+
 declare class ImportExportService {
     private db;
     private entryRepo;
@@ -2676,7 +3186,7 @@ declare class RetrievalService {
      * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
      */
     private _tieBreakSort;
-    private _withoutDrafts;
+    private _withoutIds;
     /**
      * Comparator for score + deterministic tie-break fields.
      * Negative return means "a ranks ahead of b" for descending score order.
@@ -2705,6 +3215,10 @@ declare class WriteService {
     private jobManager;
     private maintenanceService;
     constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, jobManager: JobManager, maintenanceService: MaintenanceService);
+    private inflight;
+    private track;
+    /** Await every background job this instance started (spec §6.2). Loops because a finishing job can start another. */
+    drain(): Promise<void>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
     private runLibrarianThenMaybeHeal;
     /**
@@ -2728,17 +3242,41 @@ declare class GraphTraversalService {
     traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
 }
 
+/** Supersession and history (spec 2026-09-29 §4.3). */
+declare class TemporalService {
+    private db;
+    private options;
+    private entryRepo;
+    private searchService;
+    private embeddingService;
+    constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, embeddingService: EmbeddingService);
+    /**
+     * Link `oldId` → `newId` inside the caller's transaction. `newId` must
+     * already exist. Throws WikiSupersedeError on any rule violation; the
+     * caller's transaction then rolls back.
+     */
+    supersedeInTx(tx: SQLiteAdapter, entityId: string, oldId: string, newId: string, t: number, now: number): Promise<void>;
+    supersede(entityId: string, oldId: string, replacement: SupersedeReplacement, options?: {
+        validFrom?: number;
+    }): Promise<{
+        newId: string;
+    }>;
+    history(entityId: string, factId: string): Promise<WikiFact[]>;
+}
+
 /** Typed escape hatch for tests — not part of the supported consumer API. */
 interface WikiMemoryTestAccess {
     embeddingService: EmbeddingService;
     importExportService: ImportExportService;
     ingestionService: IngestionService;
     maintenanceService: MaintenanceService;
+    maintenanceScheduler: MaintenanceScheduler;
     retrievalService: RetrievalService;
     searchService: SearchService;
     writeService: WriteService;
     promptService: PromptService;
     graphTraversalService: GraphTraversalService;
+    temporalService: TemporalService;
     entryRepo: EntryRepository;
     sourceRefIndexRepo: SourceRefIndexRepository;
     metadataRepo: MetadataRepository;
@@ -2761,6 +3299,7 @@ declare class WikiMemory {
     private jobManager;
     private ingestionService;
     private maintenanceService;
+    private maintenanceScheduler;
     private importExportService;
     private retrievalService;
     private writeService;
@@ -2769,6 +3308,7 @@ declare class WikiMemory {
     private graphTraversalService;
     private lintRepo;
     private lintService;
+    private temporalService;
     private readonly okfTrustWrites;
     constructor(db: SQLiteAdapter, options: WikiOptions);
     /**
@@ -2884,6 +3424,17 @@ declare class WikiMemory {
     traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
+    /** Await auto-mode background librarian/heal jobs started by write(). No-op in 'deferred' mode. */
+    drain(): Promise<void>;
+    /**
+     * Report which entities have pending maintenance work (librarian events
+     * behind the watermark, heal backlog, unembedded facts) without running
+     * anything. Entities with no pending work are omitted; sorted by
+     * `pendingEvents` desc then `entityId` asc.
+     */
+    getPendingMaintenance(entityIds?: string[]): Promise<PendingMaintenance[]>;
+    /** Run pending librarian/heal/reembed work under an optional token budget and deadline (spec §6.2). Nothing runs after it resolves. */
+    runPendingMaintenance(options?: RunPendingMaintenanceOptions): Promise<RunPendingMaintenanceResult>;
     /**
      * @param options.promptOverride - Applies only to this manual call. Does NOT affect
      * WriteService-triggered auto-runs. For persistent prompt customization across auto-runs,
@@ -2942,6 +3493,28 @@ declare class WikiMemory {
     getEntityStatus(entityId: string): EntityStatus;
     subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
     clearVectorCache(): void;
+    /**
+     * Brings the keyword search index up to date with SQLite after a host
+     * transaction that used `upsertGraph` has committed. Core never sees that
+     * commit, so without this the nodes stay out of keyword, hybrid and
+     * fallback retrieval until the entity's next core write.
+     *
+     * With `entityId`, rebuilds that entity if it is stale or has never been
+     * indexed; otherwise it is a no-op that still waits for rebuilds already
+     * queued. Without an argument, rebuilds every entity currently marked
+     * stale; when none is, it resolves immediately and does not wait for rebuilds
+     * already queued.
+     *
+     * Call only after the host's transaction commits: called inside it, the
+     * rebuild may index rows that later roll back, or miss them and clear the
+     * stale flag anyway. Serialized with core's internal index syncs and takes
+     * no maintenance lock. Never rejects for a valid `entityId` — on failure the
+     * entity stays stale and the next call retries it. Does not compute
+     * embeddings; that remains the maintenance sweep's job.
+     *
+     * @throws {TypeError} when `entityId` is given but is not a non-empty string.
+     */
+    syncSearchIndex(entityId?: string): Promise<void>;
     exportDump(entityIds?: string[]): Promise<MemoryDump>;
     /** Entity summary prose persisted from an OKF profile ≥ 1 import; null when none stored. */
     getEntitySummary(entityId: string): Promise<string | null>;
@@ -2963,6 +3536,18 @@ declare class WikiMemory {
         };
         metadataReset?: boolean;
     }>;
+    /**
+     * End `oldId`'s validity and link it to its replacement (spec §4.3). One
+     * transaction. Throws `WikiSupersedeError` for missing, foreign, already
+     * superseded, immutable-document, or cyclic targets.
+     */
+    supersede(entityId: string, oldId: string, replacement: SupersedeReplacement, options?: {
+        validFrom?: number;
+    }): Promise<{
+        newId: string;
+    }>;
+    /** The supersession chain containing `factId`, oldest first. [] when unknown. */
+    history(entityId: string, factId: string): Promise<WikiFact[]>;
     /**
      * Full and partial ingestion both reject foreign-owned generated fact IDs with
      * `WikiGraphNodeOwnershipConflict`. Such collisions are unexpected. Ingestion
@@ -2992,9 +3577,11 @@ declare class WikiMemory {
      * MUST be called from inside an open `db.withTransactionAsync` callback —
      * the third argument is the caller's `tx`. The method does not open a
      * nested transaction, does not acquire any lock, and does not perform
-     * post-commit work (search sync, embedding, cache eviction). Hosts that
-     * want embeddings synced should drive the existing maintenance sweep
-     * (`runLibrarian` / `runHeal` / `runOntologyBackfill` / `runPrune`,
+     * post-commit work (search sync, embedding, cache eviction). After the
+     * transaction commits, call `syncSearchIndex(entityId)` — or
+     * `syncSearchIndex()` after writing several entities in one transaction —
+     * to make the new nodes keyword-searchable. Embeddings still come from the maintenance
+     * sweep (`runLibrarian` / `runHeal` / `runOntologyBackfill` / `runPrune`,
      * scoped via `listEntityIds`).
      *
      * Contract (full pre-flight validation lives inside
@@ -3154,4 +3741,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { type WikiBusyOperation as $, type OntologyMode as A, type OntologyNodeType 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 OntologyPromptContext as J, type OntologyUpdates as K, type LLMProvider as L, type MemoryBundle as M, type PromptOverrides as N, ONTOLOGY_BACKFILL_BATCH_SIZE as O, type PendingSourceStatus as P, PromptService as Q, type ReadOptions as R, type SQLiteAdapter as S, PrunePartialFailureError as T, type ReembedResult as U, type VectorRanker as V, type WikiOptions as W, type VectorRankerFallback as X, type VectorRankerRankArgs as Y, type VectorRankerSemanticResult as Z, WikiBusyError as _, type MemoryDump as a, type WikiCheckpoint as a0, type WikiConfig as a1, type WikiDiagnostic as a2, type WikiDiagnosticCode as a3, type WikiDiagnosticDetail as a4, type WikiDiagnosticOperation as a5, type WikiDiagnosticSeverity as a6, type WikiDiagnosticTrigger as a7, WikiDraftNotFound as a8, WikiDuplicateHashError as a9, type WikiEdge as aa, type WikiEvent as ab, type WikiFact as ac, WikiGraphNodeOwnershipConflict as ad, WikiIngestEmptyError as ae, type WikiInstructions as af, WikiInvalidReadOptions as ag, type WikiLintReport as ah, type WikiMemoryTestAccess as ai, type WikiOutboxEvent as aj, WikiParseError as ak, WikiSourceRefHashCollision as al, WikiStrictOntologyViolation as am, type WikiTask as an, WikiTransactionError as ao, validateManifest as ap, EmbeddingService as aq, ImportExportService as ar, IngestionService as as, JobManager as at, MaintenanceService as au, RetrievalService as av, SearchService as aw, WriteService as ax, type FormattedMemoryDump as b, WikiMemory as c, type ClassifierAnswer as d, type ClassifierQuestion as e, type ClassifyRequest as f, type ClassifyResponse as g, type DraftPage as h, type EmbedFailureKind as i, type EmbeddingMarkerKind as j, type EntityStatus as k, type ExtractedFact as l, type ExtractedFactEdge as m, type ExtractedFactWithOntology as n, type ExtractedTask as o, type GraphTraversalOptions as p, type GroundingConfig as q, HEAL_RECHECK_MS as r, HOOK_TIMEOUT_MARKER as s, type HealResult as t, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as u, ONTOLOGY_BACKFILL_RECHECK_MS as v, type OntologyBackfillResult as w, type OntologyConfig as x, type OntologyEdgeType as y, type OntologyManifest as z };
+export { type ReembedResult as $, ONTOLOGY_BACKFILL_RECHECK_MS as A, type OntologyBackfillResult 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 OntologyConfig as J, type OntologyEdgeType as K, type LLMProvider as L, type MemoryBundle as M, type OntologyManifest as N, ONTOLOGY_BACKFILL_BATCH_SIZE as O, type OntologyMode as P, type OntologyNodeType as Q, type ReadOptions as R, type SQLiteAdapter as S, type OntologyPromptContext as T, type OntologyUpdates as U, type PendingMaintenance as V, type WikiOptions as W, type PendingSourceStatus as X, type PromptOverrides as Y, PromptService as Z, PrunePartialFailureError as _, type MemoryDump as a, type RunPendingMaintenanceOptions as a0, type RunPendingMaintenanceResult as a1, type SupersedeReplacement as a2, type VectorRanker as a3, type VectorRankerFallback as a4, type VectorRankerRankArgs as a5, type VectorRankerSemanticResult as a6, WikiBusyError as a7, type WikiBusyOperation as a8, type WikiCheckpoint as a9, validateManifest as aA, EmbeddingService as aB, ImportExportService as aC, IngestionService as aD, JobManager as aE, MaintenanceService as aF, RetrievalService as aG, SearchService as aH, WriteService as aI, type WikiConfig as aa, type WikiDiagnostic as ab, type WikiDiagnosticCode as ac, type WikiDiagnosticDetail as ad, type WikiDiagnosticOperation as ae, type WikiDiagnosticSeverity as af, type WikiDiagnosticTrigger as ag, WikiDraftNotFound as ah, WikiDuplicateHashError as ai, type WikiEdge as aj, type WikiEvent as ak, type WikiFact as al, WikiGraphNodeOwnershipConflict as am, WikiIngestEmptyError as an, type WikiInstructions as ao, WikiInvalidReadOptions as ap, type WikiLintReport as aq, type WikiMemoryTestAccess as ar, type WikiOutboxEvent as as, WikiParseError as at, WikiSourceRefHashCollision as au, WikiStrictOntologyViolation as av, WikiSupersedeError as aw, type WikiSupersedeReason as ax, type WikiTask as ay, WikiTransactionError as az, type FormattedMemoryDump as b, WikiMemory as c, type ClassifierAnswer as d, type ClassifierQuestion as e, type ClassifyRequest as f, type ClassifyResponse as g, type DraftPage as h, type EmbedFailureKind as i, type EmbeddingMarkerKind as j, type EntityMaintenanceReport as k, type EntityStatus as l, type ExtractedFact as m, type ExtractedFactEdge as n, type ExtractedFactWithOntology as o, type ExtractedTask as p, type GraphTraversalOptions as q, type GroundingConfig as r, HEAL_RECHECK_MS as s, HOOK_TIMEOUT_MARKER as t, type HealResult as u, type LibrarianConfig as v, type LibrarianGateConfig as w, type MaintenanceJob as x, type MaintenanceStopReason as y, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as z };