@equationalapplications/core-llm-wiki 7.7.7 → 7.9.0

package/dist/index.js

@@ -48,7 +48,11 @@ async function setupDatabase(db, prefix) {
       okf_usage_window TEXT,
       embedding_failed_at INTEGER,
       embedding_failure_kind TEXT,
-      embedding_attempts INTEGER NOT NULL DEFAULT 0
+      embedding_attempts INTEGER NOT NULL DEFAULT 0,
+      valid_from INTEGER,
+      valid_to INTEGER,
+      superseded_by TEXT,
+      superseded_at INTEGER
     );
 
     CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
@@ -115,7 +119,8 @@ async function setupDatabase(db, prefix) {
       event_type TEXT NOT NULL,
       summary TEXT NOT NULL,
       related_entry_id TEXT,
-      created_at INTEGER NOT NULL
+      created_at INTEGER NOT NULL,
+      occurred_at INTEGER
     );
 
     CREATE INDEX IF NOT EXISTS ${prefix}events_entity_idx ON ${prefix}events(entity_id, created_at DESC);
@@ -123,7 +128,9 @@ async function setupDatabase(db, prefix) {
     CREATE TABLE IF NOT EXISTS ${prefix}checkpoints (
       entity_id TEXT PRIMARY KEY,
       heal_checkpoint INTEGER NOT NULL DEFAULT 0,
-      memory_checkpoint INTEGER NOT NULL DEFAULT 0
+      memory_checkpoint INTEGER NOT NULL DEFAULT 0,
+      librarian_watermark_at INTEGER,
+      librarian_watermark_id TEXT
     );
 
     CREATE TABLE IF NOT EXISTS ${prefix}entity_manifests (
@@ -155,6 +162,7 @@ async function setupDatabase(db, prefix) {
       ON ${prefix}outbox (created_at);
   `);
   await createOkfV02IndexesIfColumnsExist(db, prefix);
+  await createTemporalIndexesIfColumnsExist(db, prefix);
 }
 async function createOkfV02IndexesIfColumnsExist(db, prefix) {
   for (const table of ["entries", "tasks"]) {
@@ -173,6 +181,20 @@ async function createOkfV02IndexesIfColumnsExist(db, prefix) {
     }
   }
 }
+async function createTemporalIndexesIfColumnsExist(db, prefix) {
+  const cols = await db.getAllAsync(`PRAGMA table_info(${prefix}entries)`);
+  const names = new Set(cols.map((c) => c.name));
+  if (names.has("superseded_by")) {
+    await db.execAsync(
+      `CREATE INDEX IF NOT EXISTS ${prefix}entries_superseded_idx ON ${prefix}entries(entity_id, superseded_by) WHERE superseded_by IS NOT NULL;`
+    );
+  }
+  if (names.has("valid_from") && names.has("valid_to")) {
+    await db.execAsync(
+      `CREATE INDEX IF NOT EXISTS ${prefix}entries_temporal_idx ON ${prefix}entries(entity_id) WHERE valid_from IS NOT NULL OR valid_to IS NOT NULL;`
+    );
+  }
+}
 
 // src/db/sqliteCodes.ts
 var SQLITE_RESULT_CODE_NAMES = {
@@ -341,6 +363,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/db/serializedAdapter.ts
 function isDriverError(err) {
@@ -630,6 +661,35 @@ var MIGRATIONS = [
         DROP INDEX IF EXISTS ${prefix}edges_entity_idx;
       `);
     }
+  },
+  {
+    version: 13,
+    description: "Temporal facts: valid_from/valid_to/superseded_by/superseded_at on entries, occurred_at on events, librarian watermark on checkpoints",
+    run: async (db, prefix) => {
+      const adds = [
+        ["entries", "valid_from", "INTEGER"],
+        ["entries", "valid_to", "INTEGER"],
+        ["entries", "superseded_by", "TEXT"],
+        ["entries", "superseded_at", "INTEGER"],
+        ["events", "occurred_at", "INTEGER"],
+        ["checkpoints", "librarian_watermark_at", "INTEGER"],
+        ["checkpoints", "librarian_watermark_id", "TEXT"]
+      ];
+      const existingByTable = /* @__PURE__ */ new Map();
+      for (const [table, column, type] of adds) {
+        let existing = existingByTable.get(table);
+        if (!existing) {
+          const cols = await db.getAllAsync(`PRAGMA table_info(${prefix}${table})`);
+          existing = new Set(cols.map((c) => c.name));
+          existingByTable.set(table, existing);
+        }
+        if (!existing.has(column)) {
+          await db.execAsync(`ALTER TABLE ${prefix}${table} ADD COLUMN ${column} ${type}`);
+          existing.add(column);
+        }
+      }
+      await createTemporalIndexesIfColumnsExist(db, prefix);
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -679,6 +739,24 @@ function parseJsonObject(s, fallback = null) {
   }
   return fallback;
 }
+
+// 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);
+}
 function mapRowToFact(row) {
   const tags = (() => {
     if (Array.isArray(row.tags)) return row.tags;
@@ -719,7 +797,13 @@ function mapRowToFact(row) {
     last_verified_by: row.last_verified_by ?? null,
     // Spec §2.7 + §5.3: hydrate so read() consumers don't re-call the helpers.
     isStale: coreOkf.isStaleAfter(staleAfterRaw, now),
-    trustTier: coreOkf.deriveTrustTier(okf_verified)
+    trustTier: coreOkf.deriveTrustTier(okf_verified),
+    // Temporal (spec 2026-09-29 §4, §10.8): keys appear only when set so
+    // existing deep-equality assertions and host snapshots are unchanged.
+    ...row.valid_from != null ? { valid_from: Number(row.valid_from) } : {},
+    ...row.valid_to != null ? { valid_to: Number(row.valid_to) } : {},
+    ...row.superseded_by != null ? { superseded_by: String(row.superseded_by) } : {},
+    ...row.superseded_at != null ? { superseded_at: Number(row.superseded_at) } : {}
   };
 }
 function normalizeEmbeddingBlobValue(blob) {
@@ -1140,12 +1224,14 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
    */
   async findHealCandidatesByEntityId(entityId, limit, recheckCutoff, tx) {
     const executor = this.getExecutor(tx);
+    const now = Date.now();
     const rows = await executor.getAllAsync(
       `SELECT * FROM ${this.prefix}entries
        WHERE entity_id = ? AND deleted_at IS NULL AND source_type != 'immutable_document'
+         AND ${liveAtSql("current")}
          AND (heal_checked_at IS NULL OR heal_checked_at <= ?)
        ORDER BY updated_at ASC LIMIT ?`,
-      [entityId, recheckCutoff, limit]
+      [entityId, now, now, recheckCutoff, limit]
     );
     return rows.map(mapRowToFact);
   }
@@ -1159,6 +1245,7 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
     const executor = this.getExecutor(tx);
     const columns = opts?.withBody ? "id, title, source_ref, body, lifecycle_status" : "id, title, source_ref";
     const rows = [];
+    const now = Date.now();
     for (let i = 0; i < ids.length; i += this.chunkSize) {
       const chunk = ids.slice(i, i + this.chunkSize);
       const placeholders = chunk.map(() => "?").join(", ");
@@ -1166,8 +1253,9 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
         `SELECT ${columns} FROM ${this.prefix}entries
          WHERE entity_id = ? AND deleted_at IS NULL
            AND source_type = 'immutable_document'
+           AND ${liveAtSql("current")}
            AND id IN (${placeholders})`,
-        [entityId, ...chunk]
+        [entityId, now, now, ...chunk]
       );
       rows.push(...chunkRows);
     }
@@ -1187,10 +1275,11 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
    */
   async findRecentByEntityId(entityId, limit, tx, excludeSourceRef) {
     const executor = this.getExecutor(tx);
+    const now = Date.now();
     const excludeClause = excludeSourceRef ? ` AND (source_ref IS NULL OR source_ref != ?)` : "";
-    const args = excludeSourceRef ? [entityId, excludeSourceRef, limit] : [entityId, limit];
+    const args = excludeSourceRef ? [entityId, now, now, excludeSourceRef, limit] : [entityId, now, now, limit];
     const rows = await executor.getAllAsync(
-      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL${excludeClause} ORDER BY updated_at DESC LIMIT ?`,
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL AND ${liveAtSql("current")}${excludeClause} ORDER BY updated_at DESC LIMIT ?`,
       args
     );
     return rows.map(mapRowToFact);
@@ -1398,6 +1487,97 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
       }, tx);
     }
   }
+  /** Spec §4: write any subset of the four temporal columns. Absent key = untouched; null = clear. */
+  async setTemporal(id, entityId, fields, tx, opts) {
+    const keys = ["valid_from", "valid_to", "superseded_by", "superseded_at"].filter((k) => k in fields);
+    if (keys.length === 0) return 0;
+    const executor = this.getExecutor(tx);
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET ${keys.map((k) => `${k} = ?`).join(", ")} WHERE id = ? AND entity_id = ?`,
+      [...keys.map((k) => fields[k] ?? null), id, entityId]
+    );
+    if (result.changes > 0 && opts?.outbox !== false) {
+      const payload = { id, entity_id: entityId };
+      for (const k of keys) payload[k] = fields[k] ?? null;
+      await this.outbox.push({ entityId, tableName: "entries", recordId: id, operation: "UPDATE", payload }, tx);
+    }
+    return result.changes;
+  }
+  async findTemporalRow(id, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT id, entity_id, source_type, deleted_at, created_at, valid_from, valid_to, superseded_by
+       FROM ${this.prefix}entries WHERE id = ?`,
+      [id]
+    );
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      entity_id: String(row.entity_id),
+      source_type: row.source_type,
+      deleted_at: row.deleted_at != null ? Number(row.deleted_at) : null,
+      created_at: Number(row.created_at),
+      valid_from: row.valid_from != null ? Number(row.valid_from) : null,
+      valid_to: row.valid_to != null ? Number(row.valid_to) : null,
+      superseded_by: row.superseded_by != null ? String(row.superseded_by) : 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.
+   */
+  async findNonLiveIdsByEntityIds(entityIds, mode, t, tx) {
+    if (entityIds.length === 0) return /* @__PURE__ */ new Set();
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    const temporalOnly = mode === "current" ? " AND (valid_from IS NOT NULL OR valid_to IS NOT NULL)" : "";
+    const rows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL${temporalOnly}
+         AND NOT ${liveAtSql(mode)}`,
+      [...entityIds, t, t]
+    );
+    return new Set(rows.map((r) => r.id));
+  }
+  async findSupersessionChainIds(entityId, factId, maxDepth, tx) {
+    const executor = this.getExecutor(tx);
+    const successors = await executor.getAllAsync(
+      `WITH RECURSIVE fwd(id, depth) AS (
+         SELECT superseded_by, 1 FROM ${this.prefix}entries WHERE id = ? AND entity_id = ? AND superseded_by IS NOT NULL
+         UNION
+         SELECT e.superseded_by, fwd.depth + 1 FROM fwd
+         JOIN ${this.prefix}entries e ON e.id = fwd.id AND e.entity_id = ?
+         WHERE e.superseded_by IS NOT NULL AND fwd.depth < ?
+       )
+       SELECT id FROM fwd ORDER BY depth ASC`,
+      [factId, entityId, entityId, maxDepth]
+    );
+    const predecessors = await executor.getAllAsync(
+      `WITH RECURSIVE bwd(id, depth) AS (
+         SELECT id, 1 FROM ${this.prefix}entries WHERE entity_id = ? AND superseded_by = ?
+         UNION
+         SELECT e.id, bwd.depth + 1 FROM bwd
+         JOIN ${this.prefix}entries e ON e.entity_id = ? AND e.superseded_by = bwd.id
+         WHERE bwd.depth < ?
+       )
+       SELECT id FROM bwd ORDER BY depth DESC`,
+      [entityId, factId, entityId, maxDepth]
+    );
+    const drop = (ids) => ids.map((r) => r.id).filter((id) => id !== factId);
+    return { predecessors: drop(predecessors), successors: drop(successors) };
+  }
+  async findExpiredIds(entityId, cutoff, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND valid_to IS NOT NULL AND valid_to <= ?
+       ORDER BY valid_to ASC`,
+      [entityId, cutoff]
+    );
+    return rows.map((r) => r.id);
+  }
   /**
    * Bulk soft-delete all entries for an entity.
    * Stages DELETE outbox entries for each row in the same transaction.
@@ -1830,9 +2010,11 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
     const executor = this.getExecutor(tx);
     const placeholders = entityIds.map(() => "?").join(",");
     const draftClause = opts?.excludeDrafts === true ? ` AND lifecycle_status != 'draft'` : "";
+    const liveClause = opts?.live ? ` AND ${liveAtSql(opts.live.mode)}` : "";
+    const liveArgs = opts?.live ? [opts.live.t, opts.live.t] : [];
     const rows = await executor.getAllAsync(
-      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL${draftClause} ORDER BY updated_at DESC LIMIT ?`,
-      [...entityIds, limit]
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL${draftClause}${liveClause} ORDER BY updated_at DESC LIMIT ?`,
+      [...entityIds, ...liveArgs, limit]
     );
     return rows.map(mapRowToFact);
   }
@@ -1947,13 +2129,15 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
   /** Counts live mutable facts: eligible (past cooldown) vs deferred (in cooldown). */
   async countHealCandidatesByEntityId(entityId, recheckCutoff, tx) {
     const executor = this.getExecutor(tx);
+    const now = Date.now();
     const row = await executor.getFirstAsync(
       `SELECT
          SUM(CASE WHEN heal_checked_at IS NULL OR heal_checked_at <= ? THEN 1 ELSE 0 END) AS eligible,
          SUM(CASE WHEN heal_checked_at IS NOT NULL AND heal_checked_at > ? THEN 1 ELSE 0 END) AS deferred
        FROM ${this.prefix}entries
-       WHERE entity_id = ? AND deleted_at IS NULL AND source_type != 'immutable_document'`,
-      [recheckCutoff, recheckCutoff, entityId]
+       WHERE entity_id = ? AND deleted_at IS NULL AND source_type != 'immutable_document'
+         AND ${liveAtSql("current")}`,
+      [recheckCutoff, recheckCutoff, entityId, now, now]
     );
     return { eligible: Number(row?.eligible ?? 0), deferred: Number(row?.deferred ?? 0) };
   }
@@ -1996,6 +2180,21 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
     );
     return rows.map((r) => ({ id: r.id, title: r.title }));
   }
+  /**
+   * 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).
+   */
+  async countReembedPending(entityId, maxAttempts, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS n FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND embedding_blob IS NULL AND embedding IS NULL AND embedding_attempts < ?`,
+      [entityId, maxAttempts]
+    );
+    return Number(row?.n ?? 0);
+  }
 };
 /**
  * Column list and liveness predicate shared by findMiniSearchRows and
@@ -2468,6 +2667,18 @@ var TaskRepository = class extends BaseRepository {
 };
 
 // src/repositories/EventRepository.ts
+var AFTER_SQL = "((created_at > ?) OR (created_at = ? AND id > ?))";
+function afterArgs(wm) {
+  return [wm.at, wm.at, wm.id];
+}
+function mapEvent(row) {
+  if (row.occurred_at == null) {
+    const rest = { ...row };
+    delete rest.occurred_at;
+    return rest;
+  }
+  return row;
+}
 var EventRepository = class extends BaseRepository {
   /**
    * Insert a new event row.
@@ -2476,30 +2687,32 @@ var EventRepository = class extends BaseRepository {
   async add(event, tx) {
     const executor = this.getExecutor(tx);
     await executor.runAsync(
-      `INSERT INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at, occurred_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
       [
         event.id,
         event.entity_id,
         event.event_type,
         event.summary,
         event.related_entry_id ?? null,
-        event.created_at
+        event.created_at,
+        event.occurred_at ?? null
       ]
     );
   }
   async addIgnoreDuplicate(event, tx) {
     const executor = this.getExecutor(tx);
     await executor.runAsync(
-      `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`,
+      `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at, occurred_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
       [
         event.id,
         event.entity_id,
         event.event_type,
         event.summary,
         event.related_entry_id ?? null,
-        event.created_at
+        event.created_at,
+        event.occurred_at ?? null
       ]
     );
   }
@@ -2508,10 +2721,11 @@ var EventRepository = class extends BaseRepository {
    * Defaults to a limit of 50.
    */
   async getRecent(entityId, limit = 50) {
-    return this.db.getAllAsync(
+    const rows = await this.db.getAllAsync(
       `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?`,
       [entityId, limit]
     );
+    return rows.map(mapEvent);
   }
   /**
    * Return the most recent events for the given entity IDs, newest first.
@@ -2520,10 +2734,11 @@ var EventRepository = class extends BaseRepository {
   async getRecentForEntities(entityIds, limit = 50) {
     if (entityIds.length === 0) return [];
     const placeholders = entityIds.map(() => "?").join(", ");
-    return this.db.getAllAsync(
+    const rows = await this.db.getAllAsync(
       `SELECT * FROM ${this.prefix}events WHERE entity_id IN (${placeholders}) ORDER BY created_at DESC LIMIT ?`,
       [...entityIds, limit]
     );
+    return rows.map(mapEvent);
   }
   /**
    * Delete events for an entity that were created at or before the given cutoff timestamp.
@@ -2535,6 +2750,33 @@ var EventRepository = class extends BaseRepository {
       [entityId, cutoff]
     );
   }
+  /**
+   * 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.
+   */
+  async pruneThrough(entityId, cutoff, wm) {
+    if (!wm) return { changes: 0 };
+    return this.db.runAsync(
+      `DELETE FROM ${this.prefix}events WHERE entity_id = ? AND created_at <= ? AND NOT ${AFTER_SQL}`,
+      [entityId, cutoff, ...afterArgs(wm)]
+    );
+  }
+  /**
+   * 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).
+   */
+  async countHeldBack(entityId, cutoff, wm) {
+    const where = wm ? ` AND ${AFTER_SQL}` : "";
+    const row = await this.db.getFirstAsync(
+      `SELECT COUNT(*) AS n FROM ${this.prefix}events WHERE entity_id = ? AND created_at <= ?${where}`,
+      [entityId, cutoff, ...wm ? afterArgs(wm) : []]
+    );
+    return Number(row?.n ?? 0);
+  }
   /**
    * Return the total number of events stored for an entity.
    * `tx` is optional — pass an active transaction handle for atomic reads.
@@ -2553,16 +2795,82 @@ var EventRepository = class extends BaseRepository {
    */
   async getByEntityId(entityId, limit) {
     if (limit != null) {
-      const rows = await this.db.getAllAsync(
+      const rows2 = await this.db.getAllAsync(
         `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?`,
         [entityId, limit]
       );
-      return rows.slice().reverse();
+      return rows2.map(mapEvent).slice().reverse();
     }
-    return this.db.getAllAsync(
+    const rows = await this.db.getAllAsync(
       `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at ASC`,
       [entityId]
     );
+    return rows.map(mapEvent);
+  }
+  /**
+   * 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.
+   */
+  async getAfter(entityId, wm, limit) {
+    const limitClause = limit != null ? ` LIMIT ?` : "";
+    const params = wm ? [entityId, wm.at, wm.at, wm.id] : [entityId];
+    const where = wm ? `entity_id = ? AND ${AFTER_SQL}` : `entity_id = ?`;
+    if (limit != null) params.push(limit);
+    const rows = await this.db.getAllAsync(
+      `SELECT * FROM ${this.prefix}events WHERE ${where} ORDER BY created_at ASC, id ASC${limitClause}`,
+      params
+    );
+    return rows.map(mapEvent);
+  }
+  /**
+   * 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`.
+   */
+  async countAfter(entityId, wm) {
+    const params = wm ? [entityId, wm.at, wm.at, wm.id] : [entityId];
+    const where = wm ? `entity_id = ? AND ${AFTER_SQL}` : `entity_id = ?`;
+    const row = await this.db.getFirstAsync(
+      `SELECT COUNT(*) as count FROM ${this.prefix}events WHERE ${where}`,
+      params
+    );
+    return row?.count ?? 0;
+  }
+  /**
+   * 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.
+   */
+  async getAtOffset(entityId, offset, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at ASC, id ASC LIMIT 1 OFFSET ?`,
+      [entityId, Math.max(0, Math.trunc(offset))]
+    );
+    return row ? mapEvent(row) : 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.
+   */
+  async sumSummaryCharsAfter(entityId, wm, tx) {
+    const executor = this.getExecutor(tx);
+    const params = wm ? [entityId, wm.at, wm.at, wm.id] : [entityId];
+    const where = wm ? `entity_id = ? AND ${AFTER_SQL}` : `entity_id = ?`;
+    const row = await executor.getFirstAsync(
+      `SELECT SUM(LENGTH(summary)) as total FROM ${this.prefix}events WHERE ${where}`,
+      params
+    );
+    return row?.total ?? 0;
   }
 };
 
@@ -2691,6 +2999,7 @@ var EdgeRepository = class extends BaseRepository {
           ) >= ?
           AND n.source_type NOT IN (${excludeSourceTypesPlaceholders})
           AND (? = 0 OR n.lifecycle_status != 'draft')
+          AND ${liveAtSql(opts.live.mode, "n.")}
         WHERE w.depth < ?
           AND instr(w.visited, ',' || (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END) || ',') = 0
       )
@@ -2711,6 +3020,8 @@ var EdgeRepository = class extends BaseRepository {
       minConfidenceRank,
       ...opts.excludeSourceTypes,
       opts.excludeDrafts === true ? 1 : 0,
+      opts.live.t,
+      opts.live.t,
       opts.maxDepth,
       opts.maxNodes
     ];
@@ -2960,6 +3271,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);
@@ -3279,6 +3621,16 @@ var _SearchService = class _SearchService {
     this.staleEntities.add(entityId);
     this.staleEpochs.set(entityId, (this.staleEpochs.get(entityId) ?? 0) + 1);
   }
+  /**
+   * 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.
+   */
+  async syncStale() {
+    const ids = [...this.staleEntities];
+    await Promise.all(ids.map((id) => this.syncEntries(id, [])));
+  }
   /**
    * Clears the parsed vector cache. Useful for mid-loop flush guarantees
    * or memory pressure evictions.
@@ -4482,7 +4834,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.",
@@ -4497,7 +4856,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) {
@@ -4624,6 +4990,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;
@@ -4808,6 +5189,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
@@ -4872,6 +5269,79 @@ function toGroundingAnchor(anchor) {
 var DEFAULT_MAX_CHUNK_LENGTH = 12e3;
 var DEFAULT_CHUNK_OVERLAP = 400;
 
+// 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) {
@@ -4948,7 +5418,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 = [];
@@ -5604,6 +6074,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);
@@ -5637,6 +6109,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;
@@ -5645,7 +6118,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);
@@ -5653,6 +6126,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++;
@@ -5660,6 +6134,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;
     }
@@ -5671,96 +6149,852 @@ 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;
-var ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
-var ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = 4e4;
-var ONTOLOGY_BACKFILL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
-var HEAL_ANCHOR_SEARCH_OVERFETCH = 4;
-var HEAL_MAX_PROMPT_CHARS = 4e4;
-var HEAL_BATCH_SIZE = 25;
-var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
-var MAX_EMBED_ATTEMPTS = 5;
-var EMBED_RETRY_BASE_MS = 6e4;
-var EMBED_RETRY_CAP_MS = 24 * 60 * 60 * 1e3;
-function embedRetryDelayMs(attempts) {
-  const n = Math.max(1, Math.trunc(attempts || 0));
-  const delay = EMBED_RETRY_BASE_MS * Math.pow(2, n - 1);
-  return Math.min(delay, EMBED_RETRY_CAP_MS);
-}
-function classifyReembedRow(row, now, force) {
-  if (force) return "attempt";
-  const failedAt = row.embedding_failed_at;
-  if (failedAt === null || failedAt === void 0) return "attempt";
-  if (row.embedding_failure_kind === "float32_overflow") return "permanent";
-  const attempts = row.embedding_attempts ?? 0;
-  if (attempts >= MAX_EMBED_ATTEMPTS) return "permanent";
-  return now - failedAt >= embedRetryDelayMs(attempts) ? "attempt" : "defer";
-}
-var SKIP_ERROR_LOG_CHARS = 4096;
-var formatSkipError = (err) => {
-  let base;
-  let isErrorLike = false;
+
+// 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 {
-    isErrorLike = err instanceof Error;
-  } catch {
-  }
-  if (isErrorLike || typeof err !== "object" && typeof err !== "function") {
-    base = safeErrorToString(err);
-  } else {
-    try {
-      const json = JSON.stringify(err);
-      base = typeof json === "string" ? json : safeErrorToString(err);
-    } catch {
-      base = safeErrorToString(err);
+    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) } });
     }
-  }
-  if (base.length > SKIP_ERROR_LOG_CHARS) {
-    const truncated = safeSlice(base, 0, SKIP_ERROR_LOG_CHARS);
-    return `${truncated}\u2026[+${base.length - SKIP_ERROR_LOG_CHARS} chars truncated]`;
-  }
-  return base;
-};
-var MaintenanceService = class {
-  constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
-    this.db = db;
-    this.prefix = prefix;
-    this.options = options;
-    this.entryRepo = entryRepo;
-    this.sourceRefIndexRepo = sourceRefIndexRepo;
-    this.taskRepo = taskRepo;
-    this.eventRepo = eventRepo;
-    this.metadataRepo = metadataRepo;
-    this.searchService = searchService;
-    this.jobManager = jobManager;
-    this.embeddingService = embeddingService;
-    this.ontologyService = ontologyService;
-    this.promptService = promptService ?? new PromptService(this.options.config?.prompts, resolveGrounding(this.options.config?.grounding));
-  }
-  async runPrune(entityId, options) {
-    this.jobManager.acquireLock("prune", entityId);
-    try {
-      const retainSoftDeletedFor = options?.retainSoftDeletedFor !== void 0 ? options.retainSoftDeletedFor : this.options.config?.pruneRetainSoftDeletedFor ?? 7;
-      const retainEventsFor = options?.retainEventsFor !== void 0 ? options.retainEventsFor : this.options.config?.pruneEventsAfter ?? 30;
-      const vacuum = options?.vacuum ?? false;
-      this._validatePruneDuration(retainSoftDeletedFor, "retainSoftDeletedFor");
-      this._validatePruneDuration(retainEventsFor, "retainEventsFor");
+  });
+  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/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;
+var HEAL_ANCHOR_SEARCH_OVERFETCH = 4;
+var HEAL_MAX_PROMPT_CHARS = 4e4;
+var HEAL_BATCH_SIZE = 25;
+var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
+var MAX_EMBED_ATTEMPTS = 5;
+var EMBED_RETRY_BASE_MS = 6e4;
+var EMBED_RETRY_CAP_MS = 24 * 60 * 60 * 1e3;
+function embedRetryDelayMs(attempts) {
+  const n = Math.max(1, Math.trunc(attempts || 0));
+  const delay = EMBED_RETRY_BASE_MS * Math.pow(2, n - 1);
+  return Math.min(delay, EMBED_RETRY_CAP_MS);
+}
+function classifyReembedRow(row, now, force) {
+  if (force) return "attempt";
+  const failedAt = row.embedding_failed_at;
+  if (failedAt === null || failedAt === void 0) return "attempt";
+  if (row.embedding_failure_kind === "float32_overflow") return "permanent";
+  const attempts = row.embedding_attempts ?? 0;
+  if (attempts >= MAX_EMBED_ATTEMPTS) return "permanent";
+  return now - failedAt >= embedRetryDelayMs(attempts) ? "attempt" : "defer";
+}
+var SKIP_ERROR_LOG_CHARS = 4096;
+var formatSkipError = (err) => {
+  let base;
+  let isErrorLike = false;
+  try {
+    isErrorLike = err instanceof Error;
+  } catch {
+  }
+  if (isErrorLike || typeof err !== "object" && typeof err !== "function") {
+    base = safeErrorToString(err);
+  } else {
+    try {
+      const json = JSON.stringify(err);
+      base = typeof json === "string" ? json : safeErrorToString(err);
+    } catch {
+      base = safeErrorToString(err);
+    }
+  }
+  if (base.length > SKIP_ERROR_LOG_CHARS) {
+    const truncated = safeSlice(base, 0, SKIP_ERROR_LOG_CHARS);
+    return `${truncated}\u2026[+${base.length - SKIP_ERROR_LOG_CHARS} chars truncated]`;
+  }
+  return base;
+};
+var MaintenanceService = class {
+  constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
+    this.db = db;
+    this.prefix = prefix;
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.sourceRefIndexRepo = sourceRefIndexRepo;
+    this.taskRepo = taskRepo;
+    this.eventRepo = eventRepo;
+    this.metadataRepo = metadataRepo;
+    this.searchService = searchService;
+    this.jobManager = jobManager;
+    this.embeddingService = embeddingService;
+    this.ontologyService = ontologyService;
+    this.promptService = promptService ?? new PromptService(this.options.config?.prompts, resolveGrounding(this.options.config?.grounding));
+  }
+  async runPrune(entityId, options) {
+    this.jobManager.acquireLock("prune", entityId);
+    try {
+      const retainSoftDeletedFor = options?.retainSoftDeletedFor !== void 0 ? options.retainSoftDeletedFor : this.options.config?.pruneRetainSoftDeletedFor ?? 7;
+      const retainEventsFor = options?.retainEventsFor !== void 0 ? options.retainEventsFor : this.options.config?.pruneEventsAfter ?? 30;
+      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);
@@ -5776,7 +7010,7 @@ var MaintenanceService = class {
           }
         }
         const succeededIds = succeeded.map((r) => r.id);
-        syncedIds = succeededIds;
+        syncedIds = [...syncedIds, ...succeededIds];
         await this.db.withTransactionAsync(async (tx) => {
           if (succeededIds.length > 0) {
             deletedEntries = await this.entryRepo.bulkDeletePruned(entityId, cutoff, succeededIds, tx);
@@ -5812,8 +7046,18 @@ 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();
@@ -6043,155 +7287,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.syncEntries(entityId, insertedFacts.map((f) => f.id));
-    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.
@@ -6297,7 +7458,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 {
@@ -6401,9 +7562,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,
@@ -6455,7 +7617,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. */
@@ -6499,7 +7662,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 {
@@ -6792,6 +7955,186 @@ var MaintenanceService = class {
     return sanitizeRankerError(err, this.options.sanitizeRankerErrors);
   }
 };
+
+// src/services/MaintenanceScheduler.ts
+var MaintenanceScheduler = class {
+  constructor(db, options, maintenanceService, metadataRepo, eventRepo, entryRepo, jobManager) {
+    this.db = db;
+    this.options = options;
+    this.maintenanceService = maintenanceService;
+    this.metadataRepo = metadataRepo;
+    this.eventRepo = eventRepo;
+    this.entryRepo = entryRepo;
+    this.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).
+   */
+  async getPending(entityIds) {
+    const ids = entityIds ?? await this.metadataRepo.getDistinctEntityIds();
+    const autoHealThreshold = this.options.config?.autoHealThreshold || 100;
+    const canEmbed = typeof this.options.llmProvider.embed === "function";
+    const out = [];
+    for (const entityId of ids) {
+      const wm = await this.metadataRepo.getLibrarianWatermark(entityId, this.db);
+      const pendingEvents = await this.eventRepo.countAfter(entityId, wm);
+      const chars = pendingEvents > 0 ? await this.eventRepo.sumSummaryCharsAfter(entityId, wm) : 0;
+      const eventCount = await this.eventRepo.count(entityId);
+      const cp = await this.metadataRepo.getCheckpoint(entityId, this.db);
+      let healCheckpoint = cp.heal ?? 0;
+      if (healCheckpoint > eventCount) healCheckpoint = 0;
+      const healDue = eventCount - healCheckpoint >= autoHealThreshold;
+      const reembedPending = canEmbed && await this.entryRepo.countReembedPending(entityId, MAX_EMBED_ATTEMPTS) > 0;
+      if (pendingEvents > 0 || healDue || reembedPending) {
+        out.push({ entityId, pendingEvents, pendingTokensEstimate: Math.ceil(chars / 4), healDue, reembedPending });
+      }
+    }
+    return out.sort((x, y) => y.pendingEvents - x.pendingEvents || (x.entityId < y.entityId ? -1 : x.entityId > y.entityId ? 1 : 0));
+  }
+  /**
+   * 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.
+   */
+  async run(opts = {}) {
+    if (opts.deadlineMs !== void 0 && (typeof opts.deadlineMs !== "number" || !Number.isFinite(opts.deadlineMs) || opts.deadlineMs < 0)) {
+      throw new TypeError("deadlineMs must be a finite number >= 0");
+    }
+    const meter = new UsageMeter(opts.tokenBudget);
+    const budget = opts.tokenBudget;
+    const deadline = opts.deadlineMs !== void 0 ? Date.now() + Math.max(0, opts.deadlineMs) : Infinity;
+    const jobs = new Set(opts.jobs ?? ["librarian", "heal", "reembed"]);
+    const pending = await this.getPending(opts.entityIds);
+    const states = pending.map((p) => ({
+      p,
+      report: { entityId: p.entityId, librarianPasses: 0, factsWritten: 0, healPasses: 0, reembedded: false },
+      librarian: jobs.has("librarian") && p.pendingEvents > 0,
+      heal: jobs.has("heal") && p.healDue,
+      reembed: jobs.has("reembed") && p.reembedPending
+    }));
+    let stopped = { reason: "complete" };
+    let tooSmall = null;
+    const classify = (job, entityId, requiredEstimate) => {
+      if (budget !== void 0 && requiredEstimate > budget) {
+        tooSmall ?? (tooSmall = { reason: "budget_too_small", job, entityId, requiredEstimate });
+        return "too_small";
+      }
+      return "exhausted";
+    };
+    const exhaustedStop = () => Date.now() >= deadline ? { reason: "deadline" } : { reason: "budget_exhausted" };
+    const markBusy = (st, job) => {
+      var _a;
+      ((_a = st.report).busy ?? (_a.busy = [])).push(job);
+    };
+    rounds: for (; ; ) {
+      let progressed = false;
+      for (const st of states) {
+        if (!st.librarian && !st.heal && !st.reembed) continue;
+        if (Date.now() >= deadline) {
+          stopped = { reason: "deadline" };
+          break rounds;
+        }
+        const entityId = st.p.entityId;
+        if (st.librarian) {
+          if (this.jobManager.isBlocked("librarian", entityId)) {
+            st.librarian = false;
+            markBusy(st, "librarian");
+            continue;
+          }
+          this.jobManager.acquireLock("librarian", entityId);
+          let r;
+          try {
+            r = await this.maintenanceService.runLibrarianPass({ entityId, trigger: "call", meter });
+          } finally {
+            this.jobManager.releaseLock("librarian", entityId);
+          }
+          if (r.budgetStop) {
+            if (classify("librarian", entityId, r.budgetStop.requiredEstimate) === "exhausted") {
+              stopped = exhaustedStop();
+              break rounds;
+            }
+            st.librarian = false;
+            continue;
+          }
+          if (!r.processedThrough) {
+            st.librarian = false;
+            continue;
+          }
+          st.report.librarianPasses++;
+          st.report.factsWritten += r.factsWritten;
+          progressed = true;
+          const wm = await this.metadataRepo.getLibrarianWatermark(entityId, this.db);
+          if (await this.eventRepo.countAfter(entityId, wm) === 0) st.librarian = false;
+          continue;
+        }
+        if (st.heal) {
+          if (this.jobManager.isBlocked("heal", entityId)) {
+            st.heal = false;
+            markBusy(st, "heal");
+            continue;
+          }
+          this.jobManager.acquireLock("heal", entityId);
+          let h;
+          try {
+            h = await this.maintenanceService.doRunHeal(entityId, { trigger: "call", meter });
+          } finally {
+            this.jobManager.releaseLock("heal", entityId);
+          }
+          if (h.budgetStop && h.scanned === 0) {
+            if (classify("heal", entityId, h.budgetStop.requiredEstimate) === "exhausted") {
+              stopped = exhaustedStop();
+              break rounds;
+            }
+            st.heal = false;
+            continue;
+          }
+          st.report.healPasses++;
+          progressed = true;
+          if (h.remaining === 0) {
+            st.heal = false;
+            await this.metadataRepo.updateCheckpoint(entityId, { heal: await this.eventRepo.count(entityId) }, this.db);
+          }
+          if (h.budgetStop) {
+            stopped = exhaustedStop();
+            break rounds;
+          }
+          continue;
+        }
+        if (st.reembed) {
+          st.reembed = false;
+          try {
+            await this.maintenanceService.runReembed(entityId);
+            st.report.reembedded = true;
+            progressed = true;
+          } catch (err) {
+            if (err instanceof WikiBusyError) markBusy(st, "reembed");
+            else throw err;
+          }
+        }
+      }
+      if (!progressed) break;
+    }
+    if (stopped.reason === "complete" && tooSmall) stopped = tooSmall;
+    return {
+      perEntity: states.map((s) => s.report),
+      tokensUsed: meter.used,
+      estimated: meter.estimated,
+      remaining: budget === void 0 ? null : meter.remaining,
+      stoppedReason: stopped
+    };
+  }
+};
 var MAX_EMBEDDING_BLOB_BYTES = 32 * 1024;
 var IMPORT_TITLE_MAX = 500;
 var IMPORT_BODY_MAX = 8e3;
@@ -7030,6 +8373,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);
@@ -7108,7 +8457,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
         );
@@ -7355,6 +8705,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)) {
@@ -7375,8 +8740,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);
@@ -7389,16 +8754,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);
@@ -7583,6 +8956,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 {
@@ -7618,6 +9025,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,
@@ -7637,8 +9066,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") {
@@ -7672,7 +9103,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 {
@@ -7694,9 +9125,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);
@@ -7981,7 +9412,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,
@@ -8045,7 +9476,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,
@@ -8063,13 +9494,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([
@@ -8105,8 +9541,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.
@@ -8188,6 +9624,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")) {
@@ -8214,6 +9662,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";
@@ -8224,8 +9673,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;
@@ -8247,27 +9702,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) {
@@ -8498,6 +9967,15 @@ var GraphTraversalService = class {
     const defaultMaxNodes = Number.isFinite(rawConfigDefault) && rawConfigDefault >= 1 ? Math.floor(rawConfigDefault) : fallbackMaxNodes;
     const rawMaxNodes = options.maxTraversalNodes ?? defaultMaxNodes;
     const maxNodes = Number.isFinite(rawMaxNodes) && rawMaxNodes >= 1 ? Math.floor(rawMaxNodes) : defaultMaxNodes;
+    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 rawTokenBudget = options.tokenBudget;
+    if (rawTokenBudget !== void 0 && !(typeof rawTokenBudget === "number" && Number.isFinite(rawTokenBudget) && rawTokenBudget >= 0)) {
+      throw new WikiInvalidReadOptions("tokenBudget", "must be a finite number >= 0");
+    }
+    const live = rawAsOf === void 0 ? { mode: "current", t: Date.now() } : { mode: "asOf", t: Math.trunc(rawAsOf) };
     const opts = {
       maxDepth: Math.max(1, Math.min(options.maxDepth ?? 1, 3)),
       direction: options.direction ?? this.config.traversalDirection ?? "both",
@@ -8505,16 +9983,32 @@ var GraphTraversalService = class {
       minConfidence: options.minTraversalConfidence ?? this.config.minTraversalConfidence ?? "tentative",
       excludeSourceTypes: options.excludeSourceTypes ?? this.config.excludeSourceTypes ?? [],
       excludeDrafts: options.excludeDrafts ?? this.config.excludeDrafts ?? false,
+      live,
       maxNodes
     };
     const { nodeIds, edges } = await this.edgeRepo.getNeighborhood(entityId, options.sourceId, opts);
     if (nodeIds.length === 0) return { nodes: [], edges: [] };
+    const [anchor] = await this.entryRepo.findByIds([options.sourceId], [entityId]);
+    if (anchor && !isLiveAt(anchor, live.mode, live.t)) return { nodes: [anchor], edges: [] };
     const nodes = await this.entryRepo.findByIds(nodeIds, [entityId]);
     const hydratedIds = new Set(nodes.map((node) => node.id));
     const filteredEdges = edges.filter(
       (edge) => hydratedIds.has(edge.source_id) && hydratedIds.has(edge.target_id)
     );
-    return { nodes, edges: filteredEdges };
+    if (options.tokenBudget === void 0) return { nodes, edges: filteredEdges };
+    const budget = Math.trunc(options.tokenBudget);
+    const [anchorPacked] = packFactsByBudget([nodes[0]], budget).items;
+    const kept = [anchorPacked];
+    let used = factTokenCost(anchorPacked);
+    for (const node of nodes.slice(1)) {
+      const cost = factTokenCost(node);
+      if (used + cost <= budget) {
+        kept.push(node);
+        used += cost;
+      }
+    }
+    const keptIds = new Set(kept.map((n) => n.id));
+    return { nodes: kept, edges: filteredEdges.filter((e) => keptIds.has(e.source_id) && keptIds.has(e.target_id)) };
   }
 };
 
@@ -8815,6 +10309,7 @@ var WikiMemory = class {
     this.lintService = new LintService(this.lintRepo, this.ontologyService);
     this.embeddingService = new EmbeddingService(this.db, this.options, this.entryRepo, this.metadataRepo);
     this.searchService = new SearchService(this.entryRepo);
+    this.temporalService = new TemporalService(this.db, this.options, this.entryRepo, this.searchService, this.embeddingService);
     this.jobManager = new JobManager(this.prefix);
     this.promptService = new PromptService(options.config?.prompts, resolveGrounding(options.config?.grounding));
     this.ingestionService = new IngestionService(
@@ -8846,6 +10341,15 @@ var WikiMemory = class {
       this.promptService,
       this.ontologyService
     );
+    this.maintenanceScheduler = new MaintenanceScheduler(
+      this.db,
+      this.options,
+      this.maintenanceService,
+      this.metadataRepo,
+      this.eventRepo,
+      this.entryRepo,
+      this.jobManager
+    );
     this.importExportService = new ImportExportService(
       this.db,
       this.entryRepo,
@@ -8896,11 +10400,13 @@ var WikiMemory = class {
       importExportService: this.importExportService,
       ingestionService: this.ingestionService,
       maintenanceService: this.maintenanceService,
+      maintenanceScheduler: this.maintenanceScheduler,
       retrievalService: this.retrievalService,
       searchService: this.searchService,
       writeService: this.writeService,
       promptService: this.promptService,
       graphTraversalService: this.graphTraversalService,
+      temporalService: this.temporalService,
       entryRepo: this.entryRepo,
       sourceRefIndexRepo: this.sourceRefIndexRepo,
       metadataRepo: this.metadataRepo,
@@ -9118,6 +10624,23 @@ var WikiMemory = class {
   async write(entityId, event) {
     return this.writeService.write(entityId, event);
   }
+  /** Await auto-mode background librarian/heal jobs started by write(). No-op in 'deferred' mode. */
+  async drain() {
+    return this.writeService.drain();
+  }
+  /**
+   * 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.
+   */
+  async getPendingMaintenance(entityIds) {
+    return this.maintenanceScheduler.getPending(entityIds);
+  }
+  /** Run pending librarian/heal/reembed work under an optional token budget and deadline (spec §6.2). Nothing runs after it resolves. */
+  async runPendingMaintenance(options) {
+    return this.maintenanceScheduler.run(options);
+  }
   /**
    * @param options.promptOverride - Applies only to this manual call. Does NOT affect
    * WriteService-triggered auto-runs. For persistent prompt customization across auto-runs,
@@ -9178,6 +10701,32 @@ var WikiMemory = class {
   clearVectorCache() {
     this.searchService.evictCache();
   }
+  /**
+   * 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.
+   */
+  async syncSearchIndex(entityId) {
+    if (entityId === void 0) return this.searchService.syncStale();
+    assertEntityId(entityId);
+    return this.searchService.syncEntries(entityId, []);
+  }
   async exportDump(entityIds) {
     return this.importExportService.exportDump(entityIds);
   }
@@ -9191,6 +10740,18 @@ var WikiMemory = class {
   async forget(entityId, params, opts) {
     return this.maintenanceService.forget(entityId, params, opts);
   }
+  /**
+   * 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.
+   */
+  async supersede(entityId, oldId, replacement, options) {
+    return this.temporalService.supersede(entityId, oldId, replacement, options);
+  }
+  /** The supersession chain containing `factId`, oldest first. [] when unknown. */
+  async history(entityId, factId) {
+    return this.temporalService.history(entityId, factId);
+  }
   /**
    * Full and partial ingestion both reject foreign-owned generated fact IDs with
    * `WikiGraphNodeOwnershipConflict`. Such collisions are unexpected. Ingestion
@@ -9212,9 +10773,11 @@ var WikiMemory = class {
    * 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
@@ -9509,10 +11072,11 @@ function formatContext(bundle, options) {
     maxFacts: options?.maxFacts ?? 10,
     maxTasks: options?.maxTasks ?? 10,
     maxEvents: options?.maxEvents ?? 10,
-    includeConfidence: options?.includeConfidence ?? true,
-    includeTags: options?.includeTags ?? true,
-    includeEntityIds: options?.includeEntityIds ?? false,
-    includeFactScores: options?.includeFactScores ?? false,
+    includeConfidence: !(options?.compact ?? false) && (options?.includeConfidence ?? true),
+    includeTags: !(options?.compact ?? false) && (options?.includeTags ?? true),
+    includeEntityIds: !(options?.compact ?? false) && (options?.includeEntityIds ?? false),
+    includeFactScores: !(options?.compact ?? false) && (options?.includeFactScores ?? false),
+    compact: options?.compact ?? false,
     factWeights: {
       confidence: options?.factWeights?.confidence ?? 1,
       accessCount: options?.factWeights?.accessCount ?? 0.3,
@@ -9803,7 +11367,12 @@ function factFrontmatterV2(f) {
     // `verified` key", not from "empty `verified` list").
     ...f.okf_verified && f.okf_verified.length > 0 ? { verified: f.okf_verified } : {},
     ...f.okf_sources && f.okf_sources.length > 0 ? { sources: f.okf_sources } : {},
-    ...f.okf_usage_window ? { usage_window: f.okf_usage_window } : {}
+    ...f.okf_usage_window ? { usage_window: f.okf_usage_window } : {},
+    // Temporal (spec 2026-09-29 §10.9): flat epoch-ms keys, like created_at.
+    ...f.valid_from != null ? { valid_from: f.valid_from } : {},
+    ...f.valid_to != null ? { valid_to: f.valid_to } : {},
+    ...f.superseded_by != null ? { superseded_by: f.superseded_by } : {},
+    ...f.superseded_at != null ? { superseded_at: f.superseded_at } : {}
   };
 }
 function taskFrontmatterV2(t) {
@@ -10131,9 +11700,16 @@ function frontmatterToFact(entityId, id, frontmatter, body, now) {
     okf_verified: verified,
     okf_usage_window: usageWindow,
     last_verified_at: lastV?.at ?? null,
-    last_verified_by: lastV?.by ?? null
+    last_verified_by: lastV?.by ?? null,
+    ...optionalEpoch("valid_from", frontmatter.valid_from),
+    ...optionalEpoch("valid_to", frontmatter.valid_to),
+    ...typeof frontmatter.superseded_by === "string" ? { superseded_by: frontmatter.superseded_by } : {},
+    ...optionalEpoch("superseded_at", frontmatter.superseded_at)
   };
 }
+function optionalEpoch(key, v) {
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 ? { [key]: Math.trunc(v) } : {};
+}
 function frontmatterToTask(entityId, id, frontmatter, now, usesV1StatusRule) {
   const created_at = parseFrontmatterTimestamp(frontmatter.created_at, now);
   const updated_at = parseFrontmatterTimestamp(
@@ -10390,6 +11966,7 @@ exports.WikiMemory = WikiMemory;
 exports.WikiParseError = WikiParseError;
 exports.WikiSourceRefHashCollision = WikiSourceRefHashCollision;
 exports.WikiStrictOntologyViolation = WikiStrictOntologyViolation;
+exports.WikiSupersedeError = WikiSupersedeError;
 exports.WikiTransactionError = WikiTransactionError;
 exports.chunkText = chunkText;
 exports.configureRandomSource = configureRandomSource;