@equationalapplications/core-llm-wiki 7.7.6 → 7.8.0

package/dist/{chunk-PBUZLSOM.mjs → chunk-M76CF2Q6.mjs}

@@ -176,6 +176,15 @@ var WikiDraftNotFound = class _WikiDraftNotFound extends Error {
     Object.setPrototypeOf(this, _WikiDraftNotFound.prototype);
   }
 };
+var WikiSupersedeError = class _WikiSupersedeError extends Error {
+  constructor(reason) {
+    super(`supersede() rejected: ${reason}`);
+    this.code = "WIKI_SUPERSEDE_REJECTED";
+    this.name = "WikiSupersedeError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, _WikiSupersedeError.prototype);
+  }
+};
 
 // src/utils/ids.ts
 var _injectedGetRandomValues = null;
@@ -1745,6 +1754,21 @@ function groundingEvidenceBlock(writer, cfg) {
   return `EVIDENCE REQUIREMENT: every object in "${key}" must also carry an "evidence" array of 1 to ${cfg.maxEvidence} quotes. Each quote must be an exact substring copied character-for-character from ${source} (the SOURCE section), at least ${cfg.minEvidenceChars} characters long. Do not paraphrase. Do not quote these instructions, the ontology manifest, or any existing fact. A fact whose quotes cannot be found in the SOURCE section is stored as an unreviewed draft.
 "evidence": ["exact substring copied from the SOURCE section"]`;
 }
+var OPS_EXTRACT_SYSTEM_PROMPT = `You are a memory extraction agent. Read the numbered events and extract durable facts about the user or entity, and actionable tasks.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative", "source_event": "the event label, e.g. e1", "valid_from": "optional ISO-8601 date the fact became true, only when the events state it" }],
+  "tasks": [{ "description": "string", "priority": "number (0-10)" }]
+}
+One fact per claim. Every fact must name the single event it comes from in "source_event". Do not return markdown, just raw JSON.`;
+var OPS_RESOLVE_SYSTEM_PROMPT = `You are a memory reconciliation agent. Each item has a NEW candidate fact and EXISTING facts labelled n1, n2, ... that look similar to it. Choose exactly one op per item:
+- "ADD": the candidate is new information; the existing facts are about something else.
+- "UPDATE": one existing fact states the same thing and the candidate adds detail. Give the merged "title" and "body" for that existing fact.
+- "SUPERSEDE": the candidate replaces an existing fact that is no longer true (moved, changed jobs, changed preference, reversed decision).
+- "NOOP": an existing fact already states the candidate.
+Return ONLY a valid JSON object matching this schema:
+{ "ops": [{ "item": 0, "op": "ADD|UPDATE|SUPERSEDE|NOOP", "target": "n1", "title": "UPDATE only", "body": "UPDATE only" }] }
+"target" is required for UPDATE, SUPERSEDE and NOOP and must be one of that item's own labels. Do not return markdown, just raw JSON.`;
 
 // src/utils/healConstants.ts
 var HEAL_MAX_ANCHORS = 50;
@@ -1983,6 +2007,22 @@ ${JSON.stringify(facts, null, 2)}`
 ${JSON.stringify(facts, null, 2)}`
     };
   }
+  /** Ops extract (spec §5.2): events only — no existing facts. */
+  buildOpsExtractPrompt(events, ontologyContext) {
+    const lines = events.map((l) => `${l.label} [${new Date(l.at).toISOString()}] (${l.event.event_type}) ${l.event.summary}`);
+    const grounding = this.groundingFor("librarian");
+    return {
+      systemPrompt: this.appendGrounding(this.appendOntology(OPS_EXTRACT_SYSTEM_PROMPT, ontologyContext), "librarian"),
+      userPrompt: `Events:
+${lines.join("\n")}`,
+      ...grounding ? { groundingCorpus: buildGroundingCorpus(events.map((l) => l.event.summary)) } : {}
+    };
+  }
+  /** Ops resolve (spec §5.4): only each item's own neighbours. */
+  buildOpsResolvePrompt(items) {
+    return { systemPrompt: OPS_RESOLVE_SYSTEM_PROMPT, userPrompt: `Items:
+${JSON.stringify({ items })}` };
+  }
   /**
    * The system prompt each writer would send, without hydrating data (spec
    * §8.3). `buildSystemPrompt` with no variables hydrates only ontology
@@ -2061,7 +2101,14 @@ var SEVERITY = {
   grounding_missing: "warn",
   grounding_failed: "warn",
   classification_low_confidence: "info",
-  classification_invalid: "warn"
+  classification_invalid: "warn",
+  llm_usage: "info",
+  librarian_gate: "info",
+  librarian_op_rejected: "warn",
+  contradicts_document: "warn",
+  resolve_failed: "warn",
+  read_budget: "info",
+  event_retention_held: "info"
 };
 var MESSAGE = {
   ingest_chunk_failed: "One or more document chunks failed to parse or generate.",
@@ -2076,7 +2123,14 @@ var MESSAGE = {
   grounding_missing: "A fact carried no qualifying evidence and was stored as a draft.",
   grounding_failed: "A fact carried evidence not found in its source and was stored as a draft.",
   classification_low_confidence: "A classifier answer was below the confidence threshold and was not applied.",
-  classification_invalid: "A classifier answer was invalid and was not applied."
+  classification_invalid: "A classifier answer was invalid and was not applied.",
+  llm_usage: "An LLM call completed; token usage attached.",
+  librarian_gate: "Librarian gate outcome counts for one pass.",
+  librarian_op_rejected: "A librarian reconciliation op was invalid and the candidate was added instead.",
+  contradicts_document: "A candidate contradicted a document fact and was stored as a draft.",
+  resolve_failed: "Reconciliation failed for a candidate; it was stored as a draft.",
+  read_budget: "A read was packed to a token budget.",
+  event_retention_held: "Event pruning was held back because the librarian has not processed those events yet."
 };
 var warnedNonFunction = /* @__PURE__ */ new WeakSet();
 function copyDetail(detail) {
@@ -2162,6 +2216,79 @@ function edgeDropDiagnostic(drop, ctx) {
   return { code: "edge_dropped", operation: ctx.operation, trigger: ctx.trigger, entityId: ctx.entityId, detail };
 }
 
+// src/utils/usage.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+var UsageMeter = class {
+  constructor(budget) {
+    this.used = 0;
+    this.estimated = false;
+    if (budget !== void 0 && (typeof budget !== "number" || !Number.isFinite(budget) || budget < 0)) {
+      throw new TypeError("tokenBudget must be a finite number >= 0");
+    }
+    this.budget = budget;
+  }
+  get remaining() {
+    return this.budget === void 0 ? Infinity : Math.max(0, this.budget - this.used);
+  }
+  fits(estimate) {
+    return estimate <= this.remaining;
+  }
+  record(r) {
+    this.used += r.inputTokens + r.outputTokens;
+    if (r.estimated) this.estimated = true;
+  }
+};
+var WikiBudgetExhausted = class _WikiBudgetExhausted extends Error {
+  constructor(requiredEstimate, remaining) {
+    super(`LLM call needs ~${requiredEstimate} input tokens; ${remaining} remain in the budget.`);
+    this.name = "WikiBudgetExhausted";
+    this.requiredEstimate = requiredEstimate;
+    this.remaining = remaining;
+    Object.setPrototypeOf(this, _WikiBudgetExhausted.prototype);
+  }
+};
+
+// src/utils/llmCall.ts
+function validUsage(u) {
+  if (!u || typeof u !== "object") return false;
+  const { inputTokens, outputTokens } = u;
+  return [inputTokens, outputTokens].every((n) => typeof n === "number" && Number.isFinite(n) && n >= 0);
+}
+async function callLlm(options, ctx, prompts) {
+  const promptEstimate = estimateTokens(prompts.systemPrompt) + estimateTokens(prompts.userPrompt);
+  if (ctx.meter && !ctx.meter.fits(promptEstimate)) {
+    throw new WikiBudgetExhausted(promptEstimate, ctx.meter.remaining);
+  }
+  const provider = options.llmProvider;
+  const params = { systemPrompt: prompts.systemPrompt, userPrompt: prompts.userPrompt };
+  let text;
+  let reported;
+  if (typeof provider.generateTextWithUsage === "function") {
+    const result = await provider.generateTextWithUsage(params);
+    if (!result || typeof result.text !== "string") {
+      throw new TypeError("generateTextWithUsage() must resolve to { text: string, usage? }");
+    }
+    text = result.text;
+    reported = validUsage(result.usage) ? result.usage : void 0;
+  } else {
+    text = await provider.generateText(params);
+  }
+  const record = reported ? { inputTokens: reported.inputTokens, outputTokens: reported.outputTokens, estimated: false } : { inputTokens: promptEstimate, outputTokens: estimateTokens(text), estimated: true };
+  ctx.meter?.record(record);
+  if (options.config?.reportLlmUsage === true) {
+    emitDiagnostic(options, {
+      code: "llm_usage",
+      operation: ctx.operation,
+      trigger: ctx.trigger,
+      entityId: ctx.entityId,
+      detail: { inputTokens: record.inputTokens, outputTokens: record.outputTokens, estimated: record.estimated }
+    });
+  }
+  return text;
+}
+
 // src/services/IngestionService.ts
 var LLM_PASS_DIAGNOSTIC_CODES = ["ingest_chunk_failed", "fact_rejected", "fact_deduplicated"];
 function dedupDiagnostic(entityId, sourceRef, locator) {
@@ -2238,7 +2365,7 @@ var IngestionService = class {
             ontologyContext
           );
           try {
-            const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+            const responseText = await callLlm(this.options, { operation: "ingest", entityId, trigger: "call" }, { systemPrompt, userPrompt });
             const result2 = parseJsonResponse(responseText);
             const rawFacts = Array.isArray(result2.facts) ? result2.facts : [];
             const facts = [];
@@ -2908,6 +3035,37 @@ var MetadataRepository = class extends BaseRepository {
       [entityId]
     );
   }
+  /**
+   * Read the op-based librarian's high-water mark. Returns `null` when the
+   * entity has never had its watermark set.
+   */
+  async getLibrarianWatermark(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT librarian_watermark_at, librarian_watermark_id FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+      [entityId]
+    );
+    if (!row || row.librarian_watermark_at == null || row.librarian_watermark_id == null) {
+      return null;
+    }
+    return { at: row.librarian_watermark_at, id: row.librarian_watermark_id };
+  }
+  /**
+   * Write the op-based librarian's high-water mark. Uses `ON CONFLICT`
+   * `DO UPDATE` so existing `memory_checkpoint` / `heal_checkpoint` rows
+   * are preserved verbatim.
+   */
+  async setLibrarianWatermark(entityId, wm, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}checkpoints (entity_id, memory_checkpoint, heal_checkpoint, librarian_watermark_at, librarian_watermark_id)
+       VALUES (?, 0, 0, ?, ?)
+       ON CONFLICT(entity_id) DO UPDATE SET
+         librarian_watermark_at = excluded.librarian_watermark_at,
+         librarian_watermark_id = excluded.librarian_watermark_id`,
+      [entityId, wm.at, wm.id]
+    );
+  }
   // META TABLE METHODS
   async getMeta(key, tx) {
     const executor = this.getExecutor(tx);
@@ -3080,6 +3238,8 @@ async function runBatched(args) {
   const results = [];
   const skipped = [];
   let batches = 0;
+  const settled = /* @__PURE__ */ new Set();
+  let budgetStop;
   let batchSize = initialBatchSize(maxOutputTokens);
   const trim = async (candidate) => {
     const whole = await buildPrompt(candidate);
@@ -3113,6 +3273,7 @@ async function runBatched(args) {
       } else {
         const reason = fromCall && !isTruncationError(err) && !isConfigError(err) ? "call_error" : "non_convergent";
         skipped.push({ item: batch[0], reason });
+        settled.add(batch[0]);
         onSkip?.(batch[0], err);
       }
       return;
@@ -3121,7 +3282,7 @@ async function runBatched(args) {
     const mid = Math.ceil(batch.length / 2);
     if (mid < batchSize) batchSize = mid;
     let i = 0;
-    while (i < batch.length) {
+    while (i < batch.length && !budgetStop) {
       const size = Math.min(batchSize, batch.length - i);
       const trimmed = await trim(batch.slice(i, i + size));
       await attempt(trimmed.batch, trimmed.prompts);
@@ -3129,6 +3290,7 @@ async function runBatched(args) {
     }
   };
   const attempt = async (batch, prebuilt, attemptLevel = 0) => {
+    if (budgetStop) return;
     if (batch.length === 0) return;
     const prompts = prebuilt && attemptLevel === 0 ? prebuilt : await buildPrompt(batch, attemptLevel);
     batches++;
@@ -3136,6 +3298,10 @@ async function runBatched(args) {
     try {
       responseText = await call(prompts);
     } catch (err) {
+      if (err instanceof WikiBudgetExhausted) {
+        budgetStop = { requiredEstimate: err.requiredEstimate };
+        return;
+      }
       await onFailure(batch, err, attemptLevel, true);
       return;
     }
@@ -3147,19 +3313,781 @@ async function runBatched(args) {
       return;
     }
     results.push(result);
+    for (const item of batch) settled.add(item);
   };
   let index = 0;
-  while (index < items.length) {
+  while (index < items.length && !budgetStop) {
     const { batch, prompts } = await trim(items.slice(index, index + batchSize));
     index += batch.length;
     await attempt(batch, prompts, 0);
   }
-  return { results, skipped, batches };
+  const unattempted = budgetStop ? items.filter((item) => !settled.has(item)) : [];
+  return { results, skipped, batches, unattempted, ...budgetStop ? { budgetStop } : {} };
 }
 
-// src/services/MaintenanceService.ts
+// src/services/librarian/constants.ts
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
+
+// src/services/librarian/legacy.ts
+var runLegacyLibrarianPass = async (deps, ctx) => {
+  const { entityId, trigger } = ctx;
+  const promptOverride = ctx.promptOverride;
+  const events = await deps.eventRepo.getRecent(entityId, 50);
+  const currentFactsRows = await deps.entryRepo.findRecentByEntityId(entityId, 100);
+  const currentFacts = currentFactsRows.map((f) => {
+    const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
+    return {
+      ...rest,
+      tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
+    };
+  });
+  const ontologyContext = await deps.ontologyService?.buildPromptContext(entityId) ?? null;
+  const promptEvents = events.reverse();
+  const librarianGrounding = deps.promptService.groundingFor("librarian");
+  const { systemPrompt, userPrompt, groundingCorpus: librarianCorpus = [] } = deps.promptService.buildLibrarianPrompt(
+    promptEvents,
+    currentFacts,
+    promptOverride,
+    ontologyContext
+  );
+  let responseText;
+  try {
+    responseText = await callLlm(
+      deps.options,
+      { operation: "librarian", entityId, trigger, meter: ctx.meter },
+      { systemPrompt, userPrompt }
+    );
+  } catch (err) {
+    if (err instanceof WikiBudgetExhausted) {
+      return { processedThrough: null, factsWritten: 0, budgetStop: { requiredEstimate: err.requiredEstimate } };
+    }
+    throw err;
+  }
+  const result = parseJsonResponse(responseText);
+  const facts = Array.isArray(result.facts) ? result.facts : [];
+  const tasks = Array.isArray(result.tasks) ? result.tasks : [];
+  const ontologyUpdates = result.ontology_updates;
+  const diagBuffer = new DiagnosticBuffer();
+  const diagBase = { entityId, operation: "librarian", trigger };
+  const validFacts = [];
+  const validFactItemIndexes = [];
+  facts.forEach((raw, itemIndex) => {
+    const valid = validateFact(raw);
+    if (valid) {
+      validFacts.push(valid);
+      validFactItemIndexes.push(itemIndex);
+    } else {
+      diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { itemIndex, reason: factRejectionReason(raw) } });
+    }
+  });
+  const validTasks = [];
+  tasks.forEach((raw, itemIndex) => {
+    const valid = validateTask(raw);
+    if (valid) validTasks.push(valid);
+    else diagBuffer.push({ ...diagBase, code: "task_rejected", detail: { itemIndex, reason: taskRejectionReason(raw) } });
+  });
+  const now = Date.now();
+  const insertedFacts = [];
+  await deps.db.withTransactionAsync(async (tx) => {
+    let { mode, manifest } = await deps.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+    if (mode === "emergent" && ontologyUpdates && deps.ontologyService) {
+      manifest = await deps.ontologyService.mergeEmergentUpdates(entityId, ontologyUpdates, tx);
+    }
+    const titleIndex = /* @__PURE__ */ new Map();
+    for (const existing of currentFactsRows) {
+      titleIndex.set(normalizeTitleKey(existing.title), {
+        id: existing.id,
+        okf_type: existing.okf_type ?? null
+      });
+    }
+    const factsForDedupe = await deps.entryRepo.findRecentByEntityId(entityId, 100, tx);
+    const pendingEdges = [];
+    for (const [k, fact] of validFacts.entries()) {
+      const newTokens = titleTokens(fact.title);
+      let skip = false;
+      if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+        for (const existing of factsForDedupe) {
+          if (existing.source_type !== "librarian_inferred") continue;
+          const existingTokens = titleTokens(existing.title);
+          if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+            if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
+              skip = true;
+              break;
+            }
+          }
+        }
+      }
+      if (skip) {
+        diagBuffer.push({ ...diagBase, code: "fact_deduplicated", detail: { itemIndex: validFactItemIndexes[k], reason: "fuzzy_title" } });
+        continue;
+      }
+      const ontologyFact = fact;
+      const id = generateId("fact_");
+      const validationDrops = [];
+      const normalized = deps.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false, drops: validationDrops }) ?? { okf_type: null, edges: [] };
+      for (const drop of validationDrops) diagBuffer.push(edgeDropDiagnostic(drop, { ...diagBase, factId: id }));
+      const grounding = librarianGrounding ? groundingOutcome(checkGrounding(fact.evidence, librarianCorpus, librarianGrounding), now) : null;
+      if (grounding?.diagnostic) {
+        diagBuffer.push({ ...diagBase, code: grounding.diagnostic.code, detail: { factId: id, itemIndex: validFactItemIndexes[k], reason: grounding.diagnostic.reason } });
+      }
+      const factObj = {
+        id,
+        entity_id: entityId,
+        title: fact.title,
+        body: fact.body,
+        tags: fact.tags,
+        confidence: fact.confidence,
+        source_type: "librarian_inferred",
+        source_hash: null,
+        source_ref: null,
+        created_at: now,
+        updated_at: now,
+        last_accessed_at: null,
+        access_count: 0,
+        deleted_at: null,
+        okf_type: normalized.okf_type,
+        ...grounding?.trust
+      };
+      await deps.entryRepo.upsert(factObj, tx);
+      insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+      factsForDedupe.push(factObj);
+      titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
+      if (normalized.edges.length > 0) {
+        pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+      }
+    }
+    for (const item of pendingEdges) {
+      const resolveDrops = [];
+      await deps.ontologyService?.resolveAndPersistEdges(
+        entityId,
+        item.sourceId,
+        item.sourceType,
+        item.edges ?? [],
+        manifest,
+        titleIndex,
+        tx,
+        now,
+        resolveDrops
+      );
+      for (const drop of resolveDrops) diagBuffer.push(edgeDropDiagnostic(drop, diagBase));
+    }
+    for (const task of validTasks) {
+      const id = generateId("task_");
+      const taskObj = {
+        id,
+        entity_id: entityId,
+        description: task.description,
+        status: "pending",
+        priority: task.priority,
+        created_at: now,
+        updated_at: now,
+        resolved_at: null,
+        deleted_at: null
+      };
+      await deps.taskRepo.upsert(taskObj, tx);
+    }
+  });
+  diagBuffer.flush(deps.options);
+  await deps.searchService.syncEntries(entityId, insertedFacts.map((f) => f.id));
+  for (const fact of insertedFacts) {
+    await deps.embeddingService.embedFact(fact, { operation: "librarian", trigger });
+  }
+  deps.searchService.evictCache(entityId);
+  const processedThrough = events.length > 0 ? { at: events[events.length - 1].created_at, id: events[events.length - 1].id } : null;
+  const out = { processedThrough, factsWritten: insertedFacts.length };
+  return out;
+};
+
+// src/services/librarian/ops/text.ts
+var OPS_NEIGHBOUR_BODY_CHARS = 400;
+function normalizeFactText(title, body) {
+  return `${title} ${body}`.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+function labelEvents(events) {
+  return events.map((event, i) => ({ label: `e${i + 1}`, event, at: event.occurred_at ?? event.created_at }));
+}
+function parseValidFrom(v) {
+  if (typeof v === "number") return Number.isFinite(v) && v >= 0 ? Math.trunc(v) : void 0;
+  if (typeof v === "string") {
+    const t = Date.parse(v);
+    return Number.isFinite(t) && t >= 0 ? t : void 0;
+  }
+  return void 0;
+}
+
+// src/services/librarian/ops/extract.ts
+var OPS_MAX_EVENTS_PER_PASS = 50;
+var OPS_MAX_EXTRACT_CHARS = 24e3;
+var RESOLVE_RESERVE_FACTOR = 2;
+var estimatePrompt = (p) => estimateTokens(p.systemPrompt) + estimateTokens(p.userPrompt);
+async function selectBatch(deps, entityId, wm, meter) {
+  const events = await deps.eventRepo.getAfter(entityId, wm, OPS_MAX_EVENTS_PER_PASS);
+  if (events.length === 0) return { batch: [] };
+  let n = 0;
+  let chars = 0;
+  for (const e of events) {
+    if (n > 0 && chars + e.summary.length > OPS_MAX_EXTRACT_CHARS) break;
+    chars += e.summary.length;
+    n++;
+  }
+  let batch = labelEvents(events.slice(0, n));
+  if (meter && meter.budget !== void 0) {
+    const ontologyContext = await deps.ontologyService?.buildPromptContext(entityId) ?? null;
+    for (; ; ) {
+      const need = RESOLVE_RESERVE_FACTOR * estimatePrompt(deps.promptService.buildOpsExtractPrompt(batch, ontologyContext));
+      if (meter.fits(need)) break;
+      if (batch.length === 1) return { budgetStop: { requiredEstimate: need } };
+      batch = labelEvents(events.slice(0, Math.max(1, Math.floor(batch.length / 2))));
+    }
+  }
+  return { batch };
+}
+async function runExtract(deps, ctx, batch) {
+  const { entityId, trigger } = ctx;
+  const ontologyContext = await deps.ontologyService?.buildPromptContext(entityId) ?? null;
+  const prompt = deps.promptService.buildOpsExtractPrompt(batch, ontologyContext);
+  const text = await callLlm(deps.options, { operation: "librarian", entityId, trigger, meter: ctx.meter }, prompt);
+  const parsed = parseJsonResponse(text);
+  const base = { entityId, operation: "librarian", trigger };
+  const diagnostics = [];
+  const byLabel = new Map(batch.map((l) => [l.label, l]));
+  const newestAt = batch[batch.length - 1].at;
+  const candidates = [];
+  (Array.isArray(parsed.facts) ? parsed.facts : []).forEach((raw, index) => {
+    const fact = validateFact(raw);
+    if (!fact) {
+      diagnostics.push({ ...base, code: "fact_rejected", detail: { itemIndex: index, reason: factRejectionReason(raw) } });
+      return;
+    }
+    const r = raw;
+    const sourceLabel = typeof r.source_event === "string" && byLabel.has(r.source_event) ? r.source_event : null;
+    const validFrom = parseValidFrom(r.valid_from) ?? (sourceLabel ? byLabel.get(sourceLabel).at : newestAt);
+    candidates.push({ index, fact, sourceLabel, validFrom });
+  });
+  const tasks = [];
+  (Array.isArray(parsed.tasks) ? parsed.tasks : []).forEach((raw, index) => {
+    const task = validateTask(raw);
+    if (task) tasks.push(task);
+    else diagnostics.push({ ...base, code: "task_rejected", detail: { itemIndex: index, reason: taskRejectionReason(raw) } });
+  });
+  return {
+    batch,
+    candidates,
+    tasks,
+    ...parsed.ontology_updates ? { ontologyUpdates: parsed.ontology_updates } : {},
+    groundingCorpus: prompt.groundingCorpus ?? null,
+    diagnostics
+  };
+}
+
+// src/services/librarian/ops/gate.ts
+var clamp01 = (v, d) => typeof v === "number" && Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : d;
+function resolveGateConfig(cfg) {
+  const kRaw = cfg?.k;
+  const k = typeof kRaw === "number" && Number.isFinite(kRaw) ? Math.min(20, Math.max(1, Math.trunc(kRaw))) : 5;
+  const dupThreshold = clamp01(cfg?.dupThreshold, 0.89);
+  const novelThreshold = clamp01(cfg?.novelThreshold, 0.3);
+  if (novelThreshold > dupThreshold) throw new TypeError("librarian.gate: novelThreshold must be <= dupThreshold");
+  return { k, dupThreshold, novelThreshold };
+}
+function titlesMatch(a, b) {
+  const ta = titleTokens(a);
+  const tb = titleTokens(b);
+  if (ta.size < MIN_TOKENS_TO_QUALIFY || tb.size < MIN_TOKENS_TO_QUALIFY) return false;
+  return jaccardScore(ta, tb) >= FUZZY_THRESHOLD;
+}
+function classifyCandidate(candidate, neighbours, cfg, mode) {
+  const key = normalizeFactText(candidate.title, candidate.body);
+  const same = neighbours.find((n) => normalizeFactText(n.title, n.body) === key);
+  if (same) return { kind: "noop", target: same.id };
+  if (neighbours.length === 0) return { kind: "add" };
+  if (mode === "keyword") return { kind: "ambiguous" };
+  const best = neighbours[0];
+  const score = best.score ?? 0;
+  if (score >= cfg.dupThreshold && titlesMatch(candidate.title, best.title)) return { kind: "noop", target: best.id };
+  if (score < cfg.novelThreshold) return { kind: "add" };
+  return { kind: "ambiguous" };
+}
+async function gateCandidates(deps, ctx, candidates, cfg) {
+  const { entityId, trigger } = ctx;
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  const inBatchDuplicates = [];
+  for (const c of candidates) {
+    const key = normalizeFactText(c.fact.title, c.fact.body);
+    if (seen.has(key)) inBatchDuplicates.push(c);
+    else {
+      seen.add(key);
+      unique.push(c);
+    }
+  }
+  const nonLive = await deps.entryRepo.findNonLiveIdsByEntityIds([entityId], "current", Date.now());
+  const canEmbed = typeof deps.options.llmProvider.embed === "function";
+  const stored = [];
+  if (canEmbed && unique.length > 0) {
+    for (const row of await deps.entryRepo.findWithEmbeddingsByEntityIds([entityId])) {
+      if (nonLive.has(row.id)) continue;
+      const vec = parseEmbedding(row.embedding_blob, row.embedding);
+      if (vec) stored.push({ id: row.id, vec });
+    }
+  }
+  const gated = [];
+  for (const c of unique) {
+    let ranked = null;
+    let vector = null;
+    let mode = "keyword";
+    if (canEmbed) {
+      const r = await deps.embeddingService.embedTextForFact(
+        { id: "candidate", entity_id: entityId, title: c.fact.title, body: c.fact.body, tags: c.fact.tags },
+        void 0,
+        { markFailures: false }
+      );
+      if (r.ok) {
+        vector = r.vector;
+        if (stored.length > 0 && stored.every((s) => s.vec.length === r.vector.length)) {
+          ranked = stored.map((s) => ({ id: s.id, score: cosineSimilarity(r.vector, s.vec) })).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, cfg.k);
+          mode = "vector";
+        }
+      }
+    }
+    if (!ranked) {
+      ranked = deps.searchService.searchKeyword(`${c.fact.title} ${c.fact.body}`, [entityId], cfg.k + nonLive.size).filter((h) => !nonLive.has(h.id)).slice(0, cfg.k).map((h) => ({ id: h.id, score: null }));
+    }
+    const facts = ranked.length > 0 ? await deps.entryRepo.findByIds(ranked.map((r) => r.id), [entityId]) : [];
+    const byId = new Map(facts.map((f) => [f.id, f]));
+    const neighbours = ranked.filter((r) => byId.has(r.id)).map((r, i) => {
+      const f = byId.get(r.id);
+      return { id: f.id, ref: `n${i + 1}`, title: f.title, body: f.body, source_type: f.source_type, score: r.score };
+    });
+    gated.push({ candidate: c, neighbours, decision: classifyCandidate(c.fact, neighbours, cfg, mode), vector });
+  }
+  const count = (k) => gated.filter((g) => g.decision.kind === k).length;
+  const gateDiagnostic = {
+    code: "librarian_gate",
+    operation: "librarian",
+    trigger,
+    entityId,
+    detail: { gateNoop: count("noop"), gateAdd: count("add"), gateAmbiguous: count("ambiguous") }
+  };
+  return { gated, inBatchDuplicates, gateDiagnostic };
+}
+
+// src/services/librarian/ops/resolve.ts
+var OPS_RESOLVE_MAX_PROMPT_CHARS = 4e4;
+function validateOp(raw, aliases) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  if (r.op === "ADD") return { op: "ADD" };
+  if (r.op !== "UPDATE" && r.op !== "SUPERSEDE" && r.op !== "NOOP") return null;
+  const targetId = typeof r.target === "string" ? aliases.get(r.target) : void 0;
+  if (!targetId) return null;
+  if (r.op === "NOOP") return { op: "NOOP", targetId };
+  if (r.op === "SUPERSEDE") {
+    const validFrom = parseValidFrom(r.valid_from);
+    return validFrom === void 0 ? { op: "SUPERSEDE", targetId } : { op: "SUPERSEDE", targetId, validFrom };
+  }
+  const update = { op: "UPDATE", targetId };
+  if (typeof r.title === "string" && r.title.trim() !== "") update.title = clip(r.title, 80);
+  if (typeof r.body === "string" && r.body.trim() !== "") update.body = clip(r.body, 800);
+  return update;
+}
+var aliasMapOf = (g) => new Map(g.neighbours.map((n) => [n.ref, n.id]));
+async function runResolve(deps, ctx, ambiguous) {
+  const out = { ops: /* @__PURE__ */ new Map(), rejected: [], failed: [] };
+  if (ambiguous.length === 0) return out;
+  const { entityId, trigger } = ctx;
+  const outcome = await runBatched({
+    items: ambiguous,
+    buildPrompt: (batch) => deps.promptService.buildOpsResolvePrompt(
+      batch.map((g, i) => ({
+        item: i,
+        candidate: { title: g.candidate.fact.title, body: g.candidate.fact.body },
+        existing: g.neighbours.map((n) => ({
+          ref: n.ref,
+          title: n.title,
+          body: safeSlice(n.body, 0, OPS_NEIGHBOUR_BODY_CHARS)
+        }))
+      }))
+    ),
+    call: (prompts) => callLlm(deps.options, { operation: "librarian", entityId, trigger, meter: ctx.meter }, prompts),
+    parse: (text, batch) => {
+      const parsed = parseJsonResponse(text);
+      if (!Array.isArray(parsed.ops)) throw new Error("resolve: ops missing");
+      return { batch, ops: parsed.ops };
+    },
+    maxPromptChars: OPS_RESOLVE_MAX_PROMPT_CHARS,
+    maxOutputTokens: deps.options.llmProvider.maxOutputTokens
+  });
+  if (outcome.budgetStop) return { ...out, budgetStop: outcome.budgetStop };
+  for (const { batch, ops } of outcome.results) {
+    const byItem = /* @__PURE__ */ new Map();
+    for (const raw of ops) {
+      const item = raw?.item;
+      if (typeof item === "number" && Number.isInteger(item) && item >= 0 && item < batch.length && !byItem.has(item)) {
+        byItem.set(item, raw);
+      }
+    }
+    batch.forEach((g, i) => {
+      const op = validateOp(byItem.get(i), aliasMapOf(g));
+      if (op) out.ops.set(g, op);
+      else out.rejected.push(g);
+    });
+  }
+  if (outcome.skipped.some((s) => s.reason === "call_error")) {
+    throw new Error("resolve: transient provider error; retry the pass");
+  }
+  for (const s of outcome.skipped) out.failed.push(s.item);
+  return out;
+}
+
+// src/utils/temporal.ts
+function liveAtSql(mode, alias = "") {
+  const from = mode === "asOf" ? `COALESCE(${alias}valid_from, ${alias}created_at) <= ?` : `(${alias}valid_from IS NULL OR ${alias}valid_from <= ?)`;
+  return `(${from} AND (${alias}valid_to IS NULL OR ${alias}valid_to > ?))`;
+}
+function isLiveAt(f, mode, t) {
+  if (f.deleted_at != null) return false;
+  const from = mode === "asOf" ? f.valid_from ?? f.created_at : f.valid_from;
+  if (from != null && from > t) return false;
+  return f.valid_to == null || f.valid_to > t;
+}
+function assertEpochMs(name, v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+    throw new TypeError(`${name} must be a finite epoch-ms number >= 0`);
+  }
+  return Math.trunc(v);
+}
+
+// src/services/TemporalService.ts
+var HISTORY_MAX_DEPTH = 100;
+var TemporalService = class {
+  constructor(db, options, entryRepo, searchService, embeddingService) {
+    this.db = db;
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.searchService = searchService;
+    this.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.
+   */
+  async supersedeInTx(tx, entityId, oldId, newId, t, now) {
+    const old = await this.entryRepo.findTemporalRow(oldId, tx);
+    if (!old || old.deleted_at != null) throw new WikiSupersedeError("not_found");
+    if (old.entity_id !== entityId) throw new WikiSupersedeError("cross_entity");
+    if (old.superseded_by != null) throw new WikiSupersedeError("already_superseded");
+    if (old.source_type === "immutable_document") throw new WikiSupersedeError("immutable_target");
+    if (newId === oldId) throw new WikiSupersedeError("cycle");
+    const repl = await this.entryRepo.findTemporalRow(newId, tx);
+    if (!repl || repl.deleted_at != null) throw new WikiSupersedeError("not_found");
+    if (repl.entity_id !== entityId) throw new WikiSupersedeError("cross_entity");
+    if (repl.superseded_by != null) throw new WikiSupersedeError("already_superseded");
+    const { predecessors } = await this.entryRepo.findSupersessionChainIds(entityId, oldId, HISTORY_MAX_DEPTH, tx);
+    if (predecessors.includes(newId)) throw new WikiSupersedeError("cycle");
+    await this.entryRepo.setTemporal(oldId, entityId, { valid_to: t, superseded_by: newId, superseded_at: now }, tx);
+    if (repl.valid_from == null) {
+      await this.entryRepo.setTemporal(newId, entityId, { valid_from: t }, tx);
+    }
+  }
+  async supersede(entityId, oldId, replacement, options) {
+    const now = Date.now();
+    const t = options?.validFrom === void 0 ? now : assertEpochMs("options.validFrom", options.validFrom);
+    let created = null;
+    if (typeof replacement !== "string") {
+      if (typeof replacement?.title !== "string" || replacement.title.trim() === "" || typeof replacement.body !== "string") {
+        throw new TypeError("supersede(): replacement must be a fact id or { title, body }");
+      }
+      created = {
+        id: generateId("fact_"),
+        entity_id: entityId,
+        title: replacement.title,
+        body: replacement.body,
+        tags: Array.isArray(replacement.tags) ? replacement.tags : [],
+        confidence: replacement.confidence ?? "certain",
+        source_type: replacement.source_type ?? "user_stated",
+        source_hash: null,
+        source_ref: null,
+        created_at: now,
+        updated_at: now,
+        last_accessed_at: null,
+        access_count: 0,
+        deleted_at: null
+      };
+    }
+    const newId = typeof replacement === "string" ? replacement : created.id;
+    const newValidFrom = typeof replacement !== "string" && replacement.valid_from !== void 0 ? assertEpochMs("replacement.valid_from", replacement.valid_from) : void 0;
+    await this.db.withTransactionAsync(async (tx) => {
+      if (created) {
+        await this.entryRepo.upsert(created, tx);
+        if (newValidFrom !== void 0) {
+          await this.entryRepo.setTemporal(created.id, entityId, { valid_from: newValidFrom }, tx);
+        }
+      }
+      await this.supersedeInTx(tx, entityId, oldId, newId, t, now);
+    });
+    await this.searchService.syncEntries(entityId, [oldId, newId]);
+    if (created) {
+      await this.embeddingService.embedFact(
+        { id: created.id, entity_id: entityId, title: created.title, body: created.body, tags: created.tags },
+        { operation: "supersede", trigger: "call" }
+      );
+    }
+    this.searchService.evictCache(entityId);
+    return { newId };
+  }
+  async history(entityId, factId) {
+    const start = await this.entryRepo.findTemporalRow(factId);
+    if (!start || start.entity_id !== entityId || start.deleted_at != null) return [];
+    const { predecessors, successors } = await this.entryRepo.findSupersessionChainIds(entityId, factId, HISTORY_MAX_DEPTH);
+    const facts = await this.entryRepo.findByIds([...predecessors, factId, ...successors], [entityId]);
+    return facts.sort((a, b) => (a.valid_from ?? a.created_at) - (b.valid_from ?? b.created_at) || a.created_at - b.created_at || a.id.localeCompare(b.id));
+  }
+};
+
+// src/services/librarian/ops/apply.ts
+async function applyOps(deps, ctx, input) {
+  const { entityId, trigger } = ctx;
+  const diagBase = { entityId, operation: "librarian", trigger };
+  const grounding = deps.promptService.groundingFor("librarian");
+  const temporal = new TemporalService(deps.db, deps.options, deps.entryRepo, deps.searchService, deps.embeddingService);
+  const rejected = new Set(input.rejected);
+  const failed = new Set(input.failed);
+  const written = [];
+  const updatedIds = [];
+  const now = Date.now();
+  await deps.db.withTransactionAsync(async (tx) => {
+    let { mode, manifest } = await deps.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+    if (mode === "emergent" && input.ontologyUpdates && deps.ontologyService) {
+      manifest = await deps.ontologyService.mergeEmergentUpdates(entityId, input.ontologyUpdates, tx);
+    }
+    const titleIndex = /* @__PURE__ */ new Map();
+    for (const f of await deps.entryRepo.findRecentByEntityId(entityId, 100, tx)) {
+      titleIndex.set(normalizeTitleKey(f.title), { id: f.id, okf_type: f.okf_type ?? null });
+    }
+    const pendingEdges = [];
+    const insert = async (g, draft, validFrom, overrides) => {
+      const fact = g.candidate.fact;
+      const title = overrides?.title ?? fact.title;
+      const body = overrides?.body ?? fact.body;
+      const id = generateId("fact_");
+      const drops = [];
+      const normalized = deps.ontologyService?.validateAndNormalizeFact(fact, manifest, { strict: false, drops }) ?? { okf_type: null, edges: [] };
+      for (const d of drops) input.diagnostics.push(edgeDropDiagnostic(d, { ...diagBase, factId: id }));
+      const g2 = grounding ? groundingOutcome(checkGrounding(fact.evidence, input.groundingCorpus ?? [], grounding), now) : null;
+      if (g2?.diagnostic) {
+        input.diagnostics.push({
+          ...diagBase,
+          code: g2.diagnostic.code,
+          detail: { factId: id, itemIndex: g.candidate.index, reason: g2.diagnostic.reason }
+        });
+      }
+      const row = {
+        id,
+        entity_id: entityId,
+        title,
+        body,
+        tags: fact.tags,
+        confidence: fact.confidence,
+        source_type: "librarian_inferred",
+        source_hash: null,
+        source_ref: null,
+        created_at: now,
+        updated_at: now,
+        last_accessed_at: null,
+        access_count: 0,
+        deleted_at: null,
+        okf_type: normalized.okf_type,
+        ...g2?.trust,
+        ...draft ? { lifecycle_status: "draft" } : {}
+      };
+      await deps.entryRepo.upsert(row, tx);
+      await deps.entryRepo.setTemporal(id, entityId, { valid_from: validFrom }, tx);
+      titleIndex.set(normalizeTitleKey(title), { id, okf_type: normalized.okf_type });
+      if (normalized.edges.length > 0) pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+      const textChanged = title !== fact.title || body !== fact.body;
+      written.push({ id, vector: textChanged ? null : g.vector, fact: { id, entity_id: entityId, title, body, tags: fact.tags } });
+      return id;
+    };
+    for (const g of input.gated) {
+      const idx = g.candidate.index;
+      const vf = g.candidate.validFrom;
+      if (g.decision.kind === "noop") continue;
+      if (g.decision.kind === "add") {
+        await insert(g, false, vf);
+        continue;
+      }
+      if (failed.has(g)) {
+        const id = await insert(g, true, vf);
+        input.diagnostics.push({ ...diagBase, code: "resolve_failed", detail: { factId: id, itemIndex: idx } });
+        continue;
+      }
+      const op = input.ops.get(g);
+      if (rejected.has(g) || !op) {
+        await insert(g, false, vf);
+        input.diagnostics.push({ ...diagBase, code: "librarian_op_rejected", detail: { itemIndex: idx, reason: "invalid_op" } });
+        continue;
+      }
+      if (op.op === "NOOP") continue;
+      if (op.op === "ADD") {
+        await insert(g, false, vf);
+        continue;
+      }
+      const target = g.neighbours.find((n) => n.id === op.targetId);
+      if (op.op === "UPDATE" && target.source_type === "librarian_inferred") {
+        const [existing] = await deps.entryRepo.findByIds([op.targetId], [entityId], tx);
+        if (existing) {
+          const newTitle = op.title ?? g.candidate.fact.title;
+          await deps.entryRepo.upsert({
+            ...existing,
+            title: newTitle,
+            body: op.body ?? g.candidate.fact.body,
+            updated_at: now
+          }, tx);
+          titleIndex.delete(normalizeTitleKey(existing.title));
+          titleIndex.set(normalizeTitleKey(newTitle), { id: existing.id, okf_type: existing.okf_type ?? null });
+          updatedIds.push(existing.id);
+          continue;
+        }
+      }
+      const supersedeFrom = op.op === "SUPERSEDE" && op.validFrom !== void 0 ? op.validFrom : vf;
+      const overrides = op.op === "UPDATE" ? { title: op.title, body: op.body } : void 0;
+      if (target.source_type === "immutable_document") {
+        const id = await insert(g, true, supersedeFrom, overrides);
+        input.diagnostics.push({ ...diagBase, code: "contradicts_document", detail: { factId: id, itemIndex: idx } });
+        continue;
+      }
+      const newId = await insert(g, false, supersedeFrom, overrides);
+      try {
+        await temporal.supersedeInTx(tx, entityId, op.targetId, newId, supersedeFrom, now);
+      } catch (err) {
+        if (!(err instanceof WikiSupersedeError)) throw err;
+        input.diagnostics.push({
+          ...diagBase,
+          code: "librarian_op_rejected",
+          detail: { factId: newId, itemIndex: idx, reason: err.reason }
+        });
+      }
+    }
+    for (const item of pendingEdges) {
+      const resolveDrops = [];
+      await deps.ontologyService?.resolveAndPersistEdges(
+        entityId,
+        item.sourceId,
+        item.sourceType,
+        item.edges,
+        manifest,
+        titleIndex,
+        tx,
+        now,
+        resolveDrops
+      );
+      for (const d of resolveDrops) input.diagnostics.push(edgeDropDiagnostic(d, diagBase));
+    }
+    for (const task of input.tasks) {
+      const taskObj = {
+        id: generateId("task_"),
+        entity_id: entityId,
+        description: task.description,
+        status: "pending",
+        priority: task.priority,
+        created_at: now,
+        updated_at: now,
+        resolved_at: null,
+        deleted_at: null
+      };
+      await deps.taskRepo.upsert(taskObj, tx);
+    }
+  });
+  return { written, updatedIds };
+}
+
+// src/services/librarian/ops/index.ts
+var runOpsLibrarianPass = async (deps, ctx) => {
+  const { entityId, trigger } = ctx;
+  const cfg = resolveGateConfig(deps.options.config?.librarian?.gate);
+  await deps.seedWatermark(entityId);
+  const wm = await deps.getWatermark(entityId);
+  const sel = await selectBatch(deps, entityId, wm, ctx.meter);
+  if ("budgetStop" in sel) return { processedThrough: null, factsWritten: 0, budgetStop: sel.budgetStop };
+  if (sel.batch.length === 0) return { processedThrough: null, factsWritten: 0 };
+  let ex;
+  try {
+    ex = await runExtract(deps, ctx, sel.batch);
+  } catch (err) {
+    if (err instanceof WikiBudgetExhausted) {
+      return { processedThrough: null, factsWritten: 0, budgetStop: { requiredEstimate: err.requiredEstimate } };
+    }
+    throw err;
+  }
+  const diagnostics = new DiagnosticBuffer();
+  for (const d of ex.diagnostics) diagnostics.push(d);
+  const { gated, inBatchDuplicates, gateDiagnostic } = await gateCandidates(deps, ctx, ex.candidates, cfg);
+  for (const dup of inBatchDuplicates) {
+    diagnostics.push({
+      code: "fact_deduplicated",
+      operation: "librarian",
+      trigger,
+      entityId,
+      detail: { itemIndex: dup.index, reason: "in_batch" }
+    });
+  }
+  diagnostics.push(gateDiagnostic);
+  const res = await runResolve(deps, ctx, gated.filter((g) => g.decision.kind === "ambiguous"));
+  if (res.budgetStop) {
+    diagnostics.discard();
+    return { processedThrough: null, factsWritten: 0, budgetStop: res.budgetStop };
+  }
+  const { written, updatedIds } = await applyOps(deps, ctx, {
+    gated,
+    ops: res.ops,
+    rejected: res.rejected,
+    failed: res.failed,
+    tasks: ex.tasks,
+    ontologyUpdates: ex.ontologyUpdates,
+    groundingCorpus: ex.groundingCorpus,
+    diagnostics
+  });
+  diagnostics.flush(deps.options);
+  await deps.searchService.syncEntries(entityId, [...written.map((w) => w.id), ...updatedIds]);
+  const embedCtx = { operation: "librarian", trigger };
+  for (const w of written) {
+    if (w.vector) await deps.embeddingService.storeFactVector(w.fact, w.vector, embedCtx);
+    else await deps.embeddingService.embedFact(w.fact, embedCtx);
+  }
+  if (updatedIds.length > 0) {
+    for (const f of await deps.entryRepo.findByIds(updatedIds, [entityId])) {
+      await deps.embeddingService.embedFact(
+        { id: f.id, entity_id: f.entity_id, title: f.title, body: f.body, tags: f.tags },
+        embedCtx
+      );
+    }
+  }
+  deps.searchService.evictCache(entityId);
+  const last = sel.batch[sel.batch.length - 1].event;
+  return {
+    processedThrough: { at: last.created_at, id: last.id },
+    factsWritten: written.length + updatedIds.length
+  };
+};
+
+// src/services/librarian/index.ts
+var STRATEGIES = /* @__PURE__ */ new Map([
+  ["legacy", runLegacyLibrarianPass],
+  ["ops", runOpsLibrarianPass]
+]);
+async function runLibrarianStrategy(deps, ctx) {
+  const strategy = deps.options.config?.librarian?.strategy ?? "legacy";
+  const fn = STRATEGIES.get(strategy);
+  if (!fn) {
+    throw new Error(`Unknown librarian strategy: ${strategy}`);
+  }
+  return fn(deps, ctx);
+}
+
+// src/services/MaintenanceService.ts
 var ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
 var ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = 4e4;
 var ONTOLOGY_BACKFILL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
@@ -3232,10 +4160,23 @@ var MaintenanceService = class {
       const vacuum = options?.vacuum ?? false;
       this._validatePruneDuration(retainSoftDeletedFor, "retainSoftDeletedFor");
       this._validatePruneDuration(retainEventsFor, "retainEventsFor");
+      const pruneSupersededAfter = this.options.config?.pruneSupersededAfter ?? null;
+      this._validatePruneDuration(pruneSupersededAfter, "pruneSupersededAfter");
       const now = Date.now();
+      let syncedIds = [];
       let deletedEntries = 0;
       let deletedTasks = 0;
       let deletedEvents = 0;
+      if (pruneSupersededAfter !== null) {
+        const expiredCutoff = now - pruneSupersededAfter * 864e5;
+        const expiredIds = await this.entryRepo.findExpiredIds(entityId, expiredCutoff);
+        if (expiredIds.length > 0) {
+          await this.db.withTransactionAsync(async (tx) => {
+            await this.entryRepo.softDeleteByIds(expiredIds, entityId, tx);
+          });
+          syncedIds = [...expiredIds];
+        }
+      }
       if (retainSoftDeletedFor !== null) {
         const cutoff = now - retainSoftDeletedFor * 864e5;
         const entriesToDelete = await this.entryRepo.getPrunableMetadata(entityId, cutoff);
@@ -3251,6 +4192,7 @@ var MaintenanceService = class {
           }
         }
         const succeededIds = succeeded.map((r) => r.id);
+        syncedIds = [...syncedIds, ...succeededIds];
         await this.db.withTransactionAsync(async (tx) => {
           if (succeededIds.length > 0) {
             deletedEntries = await this.entryRepo.bulkDeletePruned(entityId, cutoff, succeededIds, tx);
@@ -3258,7 +4200,7 @@ var MaintenanceService = class {
           deletedTasks = await this.taskRepo.bulkDeletePruned(entityId, cutoff, tx);
         });
         if (failure) {
-          await this.searchService.sync(entityId);
+          await this.searchService.syncEntries(entityId, syncedIds);
           const remaining = entriesToDelete.length - succeeded.length - 1;
           const isTimeout = failure.cause?.[HOOK_TIMEOUT_MARKER] === true;
           if (isTimeout) {
@@ -3286,13 +4228,23 @@ var MaintenanceService = class {
       }
       if (retainEventsFor !== null) {
         const cutoff = now - retainEventsFor * 864e5;
-        const eventResult = await this.eventRepo.prune(entityId, cutoff);
-        deletedEvents = eventResult.changes;
+        const guarded = this.options.config?.maintenance === "deferred" || this.options.config?.librarian?.strategy === "ops";
+        if (guarded) {
+          const wm = await this.metadataRepo.getLibrarianWatermark(entityId, this.db);
+          deletedEvents = (await this.eventRepo.pruneThrough(entityId, cutoff, wm)).changes;
+          const held = await this.eventRepo.countHeldBack(entityId, cutoff, wm);
+          if (held > 0) {
+            emitDiagnostic(this.options, { code: "event_retention_held", operation: "prune", trigger: "call", entityId, detail: { count: held } });
+          }
+        } else {
+          const eventResult = await this.eventRepo.prune(entityId, cutoff);
+          deletedEvents = eventResult.changes;
+        }
       }
       if (vacuum) {
         await this.metadataRepo.vacuum();
       }
-      await this.searchService.sync(entityId);
+      await this.searchService.syncEntries(entityId, syncedIds);
       return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
     } finally {
       this.jobManager.releaseLock("prune", entityId);
@@ -3462,8 +4414,8 @@ var MaintenanceService = class {
           deletedEntries += refResult;
         }
       });
-      await this.searchService.sync(entityId);
       const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
+      await this.searchService.syncEntries(entityId, uniqueDeletedIds);
       for (const factId of uniqueDeletedIds) {
         try {
           await this.embeddingService.notifyEmbeddingPersistedOrThrow(entityId, factId, null);
@@ -3517,155 +4469,72 @@ var MaintenanceService = class {
   }
   /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
   async doRunLibrarian(entityId, promptOverride, trigger = "call") {
-    const events = await this.eventRepo.getRecent(entityId, 50);
-    const currentFactsRows = await this.entryRepo.findRecentByEntityId(entityId, 100);
-    const currentFacts = currentFactsRows.map((f) => {
-      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
-      return {
-        ...rest,
-        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
-      };
-    });
-    const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
-    const promptEvents = events.reverse();
-    const librarianGrounding = this.promptService.groundingFor("librarian");
-    const { systemPrompt, userPrompt, groundingCorpus: librarianCorpus = [] } = this.promptService.buildLibrarianPrompt(
-      promptEvents,
-      currentFacts,
-      promptOverride,
-      ontologyContext
-    );
-    const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
-    const result = parseJsonResponse(responseText);
-    const facts = Array.isArray(result.facts) ? result.facts : [];
-    const tasks = Array.isArray(result.tasks) ? result.tasks : [];
-    const ontologyUpdates = result.ontology_updates;
-    const diagBuffer = new DiagnosticBuffer();
-    const diagBase = { entityId, operation: "librarian", trigger };
-    const validFacts = [];
-    const validFactItemIndexes = [];
-    facts.forEach((raw, itemIndex) => {
-      const valid = validateFact(raw);
-      if (valid) {
-        validFacts.push(valid);
-        validFactItemIndexes.push(itemIndex);
-      } else {
-        diagBuffer.push({ ...diagBase, code: "fact_rejected", detail: { itemIndex, reason: factRejectionReason(raw) } });
-      }
-    });
-    const validTasks = [];
-    tasks.forEach((raw, itemIndex) => {
-      const valid = validateTask(raw);
-      if (valid) validTasks.push(valid);
-      else diagBuffer.push({ ...diagBase, code: "task_rejected", detail: { itemIndex, reason: taskRejectionReason(raw) } });
-    });
-    const now = Date.now();
-    const insertedFacts = [];
-    await this.db.withTransactionAsync(async (tx) => {
-      let { mode, manifest } = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
-      if (mode === "emergent" && ontologyUpdates && this.ontologyService) {
-        manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontologyUpdates, tx);
-      }
-      const titleIndex = /* @__PURE__ */ new Map();
-      for (const existing of currentFactsRows) {
-        titleIndex.set(normalizeTitleKey(existing.title), {
-          id: existing.id,
-          okf_type: existing.okf_type ?? null
-        });
-      }
-      const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
-      const pendingEdges = [];
-      for (const [k, fact] of validFacts.entries()) {
-        const newTokens = titleTokens(fact.title);
-        let skip = false;
-        if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
-          for (const existing of factsForDedupe) {
-            if (existing.source_type !== "librarian_inferred") continue;
-            const existingTokens = titleTokens(existing.title);
-            if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
-              if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
-                skip = true;
-                break;
-              }
-            }
-          }
-        }
-        if (skip) {
-          diagBuffer.push({ ...diagBase, code: "fact_deduplicated", detail: { itemIndex: validFactItemIndexes[k], reason: "fuzzy_title" } });
-          continue;
-        }
-        const ontologyFact = fact;
-        const id = generateId("fact_");
-        const validationDrops = [];
-        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false, drops: validationDrops }) ?? { okf_type: null, edges: [] };
-        for (const drop of validationDrops) diagBuffer.push(edgeDropDiagnostic(drop, { ...diagBase, factId: id }));
-        const grounding = librarianGrounding ? groundingOutcome(checkGrounding(fact.evidence, librarianCorpus, librarianGrounding), now) : null;
-        if (grounding?.diagnostic) {
-          diagBuffer.push({ ...diagBase, code: grounding.diagnostic.code, detail: { factId: id, itemIndex: validFactItemIndexes[k], reason: grounding.diagnostic.reason } });
-        }
-        const factObj = {
-          id,
-          entity_id: entityId,
-          title: fact.title,
-          body: fact.body,
-          tags: fact.tags,
-          confidence: fact.confidence,
-          source_type: "librarian_inferred",
-          source_hash: null,
-          source_ref: null,
-          created_at: now,
-          updated_at: now,
-          last_accessed_at: null,
-          access_count: 0,
-          deleted_at: null,
-          okf_type: normalized.okf_type,
-          ...grounding?.trust
-        };
-        await this.entryRepo.upsert(factObj, tx);
-        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
-        factsForDedupe.push(factObj);
-        titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
-        if (normalized.edges.length > 0) {
-          pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
-        }
-      }
-      for (const item of pendingEdges) {
-        const resolveDrops = [];
-        await this.ontologyService?.resolveAndPersistEdges(
-          entityId,
-          item.sourceId,
-          item.sourceType,
-          item.edges ?? [],
-          manifest,
-          titleIndex,
-          tx,
-          now,
-          resolveDrops
-        );
-        for (const drop of resolveDrops) diagBuffer.push(edgeDropDiagnostic(drop, diagBase));
-      }
-      for (const task of validTasks) {
-        const id = generateId("task_");
-        const taskObj = {
-          id,
-          entity_id: entityId,
-          description: task.description,
-          status: "pending",
-          priority: task.priority,
-          created_at: now,
-          updated_at: now,
-          resolved_at: null,
-          deleted_at: null
-        };
-        await this.taskRepo.upsert(taskObj, tx);
-      }
-    });
-    diagBuffer.flush(this.options);
-    await this.searchService.sync(entityId);
-    for (const fact of insertedFacts) {
-      await this.embeddingService.embedFact(fact, { operation: "librarian", trigger });
+    await this.runLibrarianPass({ entityId, trigger, ...promptOverride !== void 0 ? { promptOverride } : {} });
+  }
+  /**
+   * 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.
+   */
+  async runLibrarianPass(ctx) {
+    const result = await runLibrarianStrategy(this.librarianDeps(), ctx);
+    if (result.processedThrough && !result.budgetStop) {
+      await this.advanceLibrarianWatermark(ctx.entityId, result.processedThrough);
     }
-    this.searchService.evictCache(entityId);
+    return result;
+  }
+  /**
+   * 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.
+   */
+  librarianDeps() {
+    return {
+      db: this.db,
+      options: this.options,
+      entryRepo: this.entryRepo,
+      taskRepo: this.taskRepo,
+      eventRepo: this.eventRepo,
+      searchService: this.searchService,
+      embeddingService: this.embeddingService,
+      promptService: this.promptService,
+      ontologyService: this.ontologyService,
+      seedWatermark: (entityId) => this.seedLibrarianWatermark(entityId),
+      getWatermark: (entityId) => this.metadataRepo.getLibrarianWatermark(entityId, this.db)
+    };
+  }
+  /**
+   * 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.
+   */
+  async advanceLibrarianWatermark(entityId, next) {
+    const current = await this.metadataRepo.getLibrarianWatermark(entityId, this.db);
+    const newer = !current || next.at > current.at || next.at === current.at && next.id > current.id;
+    if (newer) await this.metadataRepo.setLibrarianWatermark(entityId, next, this.db);
+  }
+  /**
+   * 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`.
+   */
+  async seedLibrarianWatermark(entityId) {
+    if (await this.metadataRepo.getLibrarianWatermark(entityId, this.db)) return;
+    const cp = await this.metadataRepo.getCheckpoint(entityId, this.db);
+    const memory = cp.memory ?? 0;
+    if (memory <= 0) return;
+    const total = await this.eventRepo.count(entityId);
+    const ev = await this.eventRepo.getAtOffset(entityId, Math.min(memory, total) - 1);
+    if (ev) await this.metadataRepo.setLibrarianWatermark(entityId, { at: ev.created_at, id: ev.id }, this.db);
   }
   /**
    * Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook.
@@ -3719,7 +4588,7 @@ var MaintenanceService = class {
     }
     const healCandidates = await this.entryRepo.findHealCandidatesByEntityId(entityId, batchSize, recheckCutoff);
     if (healCandidates.length === 0) {
-      await this.searchService.sync(entityId);
+      await this.searchService.syncEntries(entityId, Array.from(/* @__PURE__ */ new Set([...orphanedIds, ...staleDowngradedIds])));
       this.searchService.evictCache(entityId);
       const counts2 = await this.entryRepo.countHealCandidatesByEntityId(entityId, recheckCutoff);
       return {
@@ -3771,7 +4640,7 @@ var MaintenanceService = class {
         if (groundingCorpus !== void 0) corpusByPrompt.set(prompts, groundingCorpus);
         return prompts;
       },
-      call: (prompts) => this.options.llmProvider.generateText(prompts),
+      call: (prompts) => callLlm(this.options, { operation: "heal", entityId, trigger, meter: options?.meter }, prompts),
       parse: (responseText, batch, prompts) => {
         const result = parseJsonResponse(responseText);
         return {
@@ -3875,9 +4744,10 @@ var MaintenanceService = class {
       const callErrorIds = new Set(
         outcome.skipped.filter((s) => s.reason === "call_error").map((s) => s.item.id)
       );
+      const unattemptedIds = new Set(outcome.unattempted.map((f) => f.id));
       await this.entryRepo.markHealChecked(
         [
-          ...healCandidates.map((f) => f.id).filter((id) => !callErrorIds.has(id)),
+          ...healCandidates.map((f) => f.id).filter((id) => !callErrorIds.has(id) && !unattemptedIds.has(id)),
           ...insertedFacts.map((f) => f.id)
         ],
         entityId,
@@ -3889,7 +4759,14 @@ var MaintenanceService = class {
       diagBuffer.push({ ...diagBase, code: "heal_skipped", detail: { factId: item.id, reason } });
     }
     diagBuffer.flush(this.options);
-    await this.searchService.sync(entityId);
+    const healSyncIds = Array.from(/* @__PURE__ */ new Set([
+      ...orphanedIds,
+      ...staleDowngradedIds,
+      ...safeDowngraded,
+      ...uniqueDeletedFactIds,
+      ...insertedFacts.map((f) => f.id)
+    ]));
+    await this.searchService.syncEntries(entityId, healSyncIds);
     for (const factId of uniqueDeletedFactIds) {
       try {
         await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
@@ -3922,7 +4799,8 @@ var MaintenanceService = class {
       skipped: outcome.skipped.map(({ item, reason }) => ({ id: item.id, reason })),
       degraded: healedDegraded,
       remaining: counts.eligible,
-      deferred: counts.deferred
+      deferred: counts.deferred,
+      ...outcome.budgetStop ? { budgetStop: outcome.budgetStop } : {}
     };
   }
   /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
@@ -3966,7 +4844,7 @@ var MaintenanceService = class {
     const outcome = await runBatched({
       items: candidates,
       buildPrompt,
-      call: (prompts) => this.options.llmProvider.generateText(prompts),
+      call: (prompts) => callLlm(this.options, { operation: "ontologyBackfill", entityId, trigger: "call" }, prompts),
       parse: (responseText, batch) => {
         const parsed = parseJsonResponse(responseText);
         return {
@@ -4497,6 +5375,12 @@ var ImportExportService = class {
           })()
         };
         await this.entryRepo.upsertForImport(factObj, tx);
+        await this.entryRepo.setTemporal(fact.id, entityId, {
+          valid_from: fact.valid_from ?? null,
+          valid_to: fact.valid_to ?? null,
+          superseded_by: fact.superseded_by ?? null,
+          superseded_at: fact.superseded_at ?? null
+        }, tx, { outbox: false });
         if (blobData != null) {
           factsWithPreservedBlob.set(fact.id, blobData);
           if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
@@ -4575,7 +5459,8 @@ var ImportExportService = class {
             event_type: event.event_type,
             summary: event.summary,
             related_entry_id: event.related_entry_id ?? null,
-            created_at: event.created_at
+            created_at: event.created_at,
+            occurred_at: event.occurred_at ?? null
           },
           tx
         );
@@ -4822,6 +5707,21 @@ var EmbeddingService = class {
     }
   }
   async tryEmbedFact(fact, ctx) {
+    const r = await this.embedTextForFact(fact, ctx);
+    return r.ok ? this.storeFactVector(fact, r.vector, ctx) : r;
+  }
+  /**
+   * 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.
+   */
+  async embedTextForFact(fact, ctx, opts) {
+    const markFailures = opts?.markFailures !== false;
     if (typeof this.options.llmProvider.embed !== "function") return { ok: false, kind: "no_provider" };
     let tagsStr;
     if (Array.isArray(fact.tags)) {
@@ -4842,8 +5742,8 @@ var EmbeddingService = class {
       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");
-        await this.markFailure(fact.id, "invalid_vector");
+        if (markFailures) this.reportEmbed(ctx, fact, "embedding_failed", "invalid_vector");
+        if (markFailures) await this.markFailure(fact.id, "invalid_vector");
         return { ok: false, kind: "invalid_vector" };
       }
       float32Vector = new Float32Array(vector);
@@ -4856,16 +5756,24 @@ var EmbeddingService = class {
       }
       if (hasNonFinite) {
         console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
-        this.reportEmbed(ctx, fact, "embedding_failed", "float32_overflow");
-        await this.markFailure(fact.id, "float32_overflow");
+        if (markFailures) this.reportEmbed(ctx, fact, "embedding_failed", "float32_overflow");
+        if (markFailures) await this.markFailure(fact.id, "float32_overflow");
         return { ok: false, kind: "float32_overflow" };
       }
     } catch (err) {
       console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
-      this.reportEmbed(ctx, fact, "embedding_failed", "embed_threw");
-      await this.markFailure(fact.id, "provider_error");
+      if (markFailures) this.reportEmbed(ctx, fact, "embedding_failed", "embed_threw");
+      if (markFailures) await this.markFailure(fact.id, "provider_error");
       return { ok: false, kind: "provider_error" };
     }
+    return { ok: true, vector: float32Vector };
+  }
+  /**
+   * 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).
+   */
+  async storeFactVector(fact, float32Vector, ctx) {
     try {
       await this.storeEmbeddingDimension(float32Vector.length);
       const blob = new Uint8Array(float32Vector.buffer);
@@ -5050,6 +5958,40 @@ function selectWithFloors(sortedRows, floors, maxResults) {
   return Array.from(selected).sort((a, b) => a - b).map((i) => sortedRows[i]);
 }
 
+// src/utils/budget.ts
+function factTokenCost(f) {
+  return estimateTokens(`${f.title} ${f.body} ${f.tags.join(" ")}`);
+}
+function packFactsByBudget(items, budget, scores) {
+  const candidates = items.length;
+  if (candidates === 0) return { items: [], tokensUsed: 0, candidates: 0, packed: 0 };
+  let top = items[0];
+  let topCost = factTokenCost(top);
+  if (topCost > budget) {
+    const overhead = estimateTokens(`${top.title}  ${top.tags.join(" ")}`);
+    top = { ...top, body: safeSlice(top.body, 0, Math.max(0, (budget - overhead) * 4)) };
+    topCost = factTokenCost(top);
+  }
+  const kept = [{ rank: 0, item: top }];
+  let used = topCost;
+  const rest = items.slice(1).map((item, i) => {
+    const rank = i + 1;
+    const cost = factTokenCost(item);
+    const s = scores?.get(item.id);
+    const value = typeof s === "number" && Number.isFinite(s) && s > 0 ? s : 1 / (rank + 1);
+    return { rank, item, cost, density: value / Math.max(1, cost) };
+  });
+  rest.sort((a, b) => b.density - a.density || a.rank - b.rank);
+  for (const r of rest) {
+    if (used + r.cost <= budget) {
+      kept.push({ rank: r.rank, item: r.item });
+      used += r.cost;
+    }
+  }
+  kept.sort((a, b) => a.rank - b.rank);
+  return { items: kept.map((k) => k.item), tokensUsed: used, candidates, packed: kept.length };
+}
+
 // src/services/RetrievalService.ts
 var EMPTY_ID_SET = /* @__PURE__ */ new Set();
 var RetrievalService = class {
@@ -5085,6 +6027,28 @@ 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 rawAsOf = options?.asOf;
+    if (rawAsOf !== void 0 && !(typeof rawAsOf === "number" && Number.isFinite(rawAsOf) && rawAsOf >= 0)) {
+      throw new WikiInvalidReadOptions("asOf", "must be a finite epoch-ms number >= 0");
+    }
+    const tokenBudget = options?.tokenBudget;
+    if (tokenBudget !== void 0 && !(typeof tokenBudget === "number" && Number.isFinite(tokenBudget) && tokenBudget >= 0)) {
+      throw new WikiInvalidReadOptions("tokenBudget", "must be a finite number >= 0");
+    }
+    const applyBudget = (input) => {
+      if (tokenBudget === void 0) return input;
+      const packed = packFactsByBudget(input, Math.trunc(tokenBudget), scoreByFactId);
+      emitDiagnostic(this.options, {
+        code: "read_budget",
+        operation: "read",
+        trigger: "call",
+        entityId: entityIds.length === 1 ? entityIds[0] : entityIds.join(","),
+        detail: { candidates: packed.candidates, packed: packed.packed, tokensUsed: packed.tokensUsed }
+      });
+      return packed.items;
+    };
+    const liveMode = rawAsOf === void 0 ? "current" : "asOf";
+    const liveAt = rawAsOf === void 0 ? Date.now() : Math.trunc(rawAsOf);
     const trimmedQuery = query.trim();
     const sanitizedTierFloors = trimmedQuery && exposeMetadata ? validateTierFloors(
       entityIds,
@@ -5104,8 +6068,10 @@ var RetrievalService = class {
       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;
+      const nonLiveIds = scoredEntityIds.length > 0 ? await this.entryRepo.findNonLiveIdsByEntityIds(scoredEntityIds, liveMode, liveAt) : EMPTY_ID_SET;
+      const excludedIds = draftIds.size === 0 ? nonLiveIds : nonLiveIds.size === 0 ? draftIds : /* @__PURE__ */ new Set([...draftIds, ...nonLiveIds]);
+      const excludedPad = excludedIds.size;
+      const padLimit = (n) => n >= Number.MAX_SAFE_INTEGER ? n : n + excludedPad;
       if (scoredEntityIds.length === 0) {
         usedEmbed = true;
       } else if (!skipEmbed && typeof this.options.llmProvider.embed === "function") {
@@ -5139,7 +6105,7 @@ var RetrievalService = class {
           let miniSearchScores;
           if (effectivePreFilterLimit !== void 0) {
             populateCache = false;
-            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER).filter((r) => !draftIds.has(r.id));
+            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER).filter((r) => !excludedIds.has(r.id));
             if (preResults.length === 0) {
               candidateRows = null;
             } else {
@@ -5161,9 +6127,9 @@ var RetrievalService = class {
             }
           } else {
             if (useRanker) {
-              candidateRows = this._withoutDrafts(await this.entryRepo.findMetadataByEntityIds(scoredEntityIds), draftIds);
+              candidateRows = this._withoutIds(await this.entryRepo.findMetadataByEntityIds(scoredEntityIds), excludedIds);
             } else {
-              candidateRows = this._withoutDrafts(await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds), draftIds);
+              candidateRows = this._withoutIds(await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds), excludedIds);
             }
             if (weight !== void 0 && weight < 1) {
               miniSearchScores = this.searchService.getMiniSearchScores(trimmedQuery, scoredEntityIds);
@@ -5448,7 +6414,7 @@ var RetrievalService = class {
                 // read() re-sorts after applying tier weights
               });
             }
-            if (draftPad > 0) scored = scored.filter((s) => !draftIds.has(s.id));
+            if (excludedPad > 0) scored = scored.filter((s) => !excludedIds.has(s.id));
             if (scored.length > 0) {
               scored = scored.map((row) => ({
                 ...row,
@@ -5512,7 +6478,7 @@ 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 : padLimit(Math.max(maxResults * 2, maxResults + 50));
-        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit).filter((r) => !draftIds.has(r.id));
+        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit).filter((r) => !excludedIds.has(r.id));
         const candidates = results.map((r) => ({
           id: r.id,
           entity_id: r.entity_id,
@@ -5530,13 +6496,18 @@ var RetrievalService = class {
           }
         }
       }
+      facts = applyBudget(facts);
       if (facts.length > 0) {
         const ids = facts.map((f) => f.id);
         const now = Date.now();
         await this.entryRepo.trackAccess(ids, now);
       }
     } else {
-      facts = excludeDrafts ? await this.entryRepo.findRecentByEntityIds(entityIds, maxResults, void 0, { excludeDrafts: true }) : await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
+      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults, void 0, {
+        ...excludeDrafts ? { excludeDrafts: true } : {},
+        live: { mode: liveMode, t: liveAt }
+      });
+      facts = applyBudget(facts);
     }
     const eventsLimit = Math.min(10 * entityIds.length, 100);
     const [tasks, events] = await Promise.all([
@@ -5572,8 +6543,8 @@ 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));
+  _withoutIds(rows, excludeIds) {
+    return excludeIds.size === 0 ? rows : rows.filter((row) => !excludeIds.has(row.id));
   }
   /**
    * Comparator for score + deterministic tie-break fields.
@@ -5655,6 +6626,18 @@ var WriteService = class {
     this.metadataRepo = metadataRepo;
     this.jobManager = jobManager;
     this.maintenanceService = maintenanceService;
+    this.inflight = /* @__PURE__ */ new Set();
+  }
+  track(p) {
+    this.inflight.add(p);
+    p.finally(() => this.inflight.delete(p)).catch(() => {
+    });
+  }
+  /** Await every background job this instance started (spec §6.2). Loops because a finishing job can start another. */
+  async drain() {
+    while (this.inflight.size > 0) {
+      await Promise.allSettled([...this.inflight]);
+    }
   }
   async write(entityId, event) {
     if (typeof entityId !== "string" || entityId.length === 0 || entityId.length > 200 || entityId.includes("\0")) {
@@ -5681,6 +6664,7 @@ var WriteService = class {
     }
     const id = generateId("evt_");
     const now = Date.now();
+    const occurredAt = event.occurred_at == null ? null : assertEpochMs("event.occurred_at", event.occurred_at);
     let eventType = event.event_type;
     if (!["observation", "decision", "action", "outcome"].includes(eventType)) {
       eventType = "observation";
@@ -5691,8 +6675,14 @@ var WriteService = class {
       event_type: eventType,
       summary,
       related_entry_id: relatedEntryId,
-      created_at: now
+      created_at: now,
+      occurred_at: occurredAt
     };
+    const deferred = this.options.config?.maintenance === "deferred";
+    if (deferred) {
+      await this.eventRepo.add(newEvent);
+      return;
+    }
     let shouldRunLibrarian = false;
     let librarianCount = 0;
     let prevMemoryCheckpoint = 0;
@@ -5714,27 +6704,41 @@ var WriteService = class {
           prevMemoryCheckpoint = memoryCheckpoint;
           await this.metadataRepo.updateCheckpoint(entityId, { memory: count }, tx);
         }
+      } else {
+        const tokenThreshold = this.options.config?.autoLibrarianTokenThreshold;
+        if (typeof tokenThreshold === "number" && tokenThreshold > 0 && !this.jobManager.isBlocked("librarian", entityId)) {
+          const wm = await this.metadataRepo.getLibrarianWatermark(entityId, tx);
+          const chars = await this.eventRepo.sumSummaryCharsAfter(entityId, wm, tx);
+          if (Math.ceil(chars / 4) >= tokenThreshold) {
+            shouldRunLibrarian = true;
+            librarianCount = count;
+            prevMemoryCheckpoint = memoryCheckpoint;
+            await this.metadataRepo.updateCheckpoint(entityId, { memory: count }, tx);
+          }
+        }
       }
     });
     if (shouldRunLibrarian) {
       try {
         this.jobManager.acquireLock("librarian", entityId);
         const stage = { job: "librarian" };
-        this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint, stage).catch((err) => {
+        const job = this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint, stage).catch((err) => {
           console.error(err);
           this.reportBackgroundFailure(entityId, stage.job);
         }).finally(() => {
           this.jobManager.releaseLock("librarian", entityId);
         });
+        this.track(job);
       } catch (e) {
         if (!(e instanceof WikiBusyError)) throw e;
         await this.metadataRepo.updateCheckpoint(entityId, { memory: prevMemoryCheckpoint }, this.db);
       }
     } else if (!this.jobManager.isBlocked("librarian", entityId)) {
-      this.maybeRunHeal(entityId, eventCount).catch((err) => {
+      const healJob = this.maybeRunHeal(entityId, eventCount).catch((err) => {
         console.error(err);
         this.reportBackgroundFailure(entityId, "heal");
       });
+      this.track(healJob);
     }
   }
   async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint, stage) {
@@ -5781,6 +6785,6 @@ var WriteService = class {
   }
 };
 
-export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, edgeTripleAllowed, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveGrounding, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-PBUZLSOM.mjs.map
-//# sourceMappingURL=chunk-PBUZLSOM.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MAX_EMBED_ATTEMPTS, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, TemporalService, UsageMeter, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, edgeTripleAllowed, emptyManifest, entitySummaryMetaKey, extractSqliteCode, factTokenCost, generateId, isLiveAt, liveAtSql, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, packFactsByBudget, parseEmbedding, resolveEdgeDefinitions, resolveGrounding, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-M76CF2Q6.mjs.map
+//# sourceMappingURL=chunk-M76CF2Q6.mjs.map