@equationalapplications/core-llm-wiki 7.7.6 → 7.8.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { BaseRepository, WikiGraphNodeOwnershipConflict, __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, WikiTransactionError, extractSqliteCode } from './chunk-PBUZLSOM.mjs';
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-PBUZLSOM.mjs';
+import { BaseRepository, WikiGraphNodeOwnershipConflict, liveAtSql, __privateAdd, MetadataRepository, EmbeddingService, SearchService, TemporalService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, MAX_EMBED_ATTEMPTS, UsageMeter, WikiBusyError, WikiInvalidReadOptions, isLiveAt, packFactsByBudget, factTokenCost, WikiTransactionError, extractSqliteCode } from './chunk-M76CF2Q6.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-M76CF2Q6.mjs';
 import { deriveTrustTier, isStaleAfter, appendRelatedSection, buildConceptDocument, buildLogMd, buildEntityIndexMd, buildRootIndexMd, isAllowedOkfPath, parseRootIndexMd, parseEntityIndexMd, parseConcept, splitRelatedSection, extractMarkdownLinks, parseLogMd, parseEventIdComment, latestVerified, formatSourcesJson, appendEventIdComment, parseVerifiedFlexible, parseCitationsList } from '@equationalapplications/core-okf';
 
 // src/db/schema.ts
@@ -35,7 +35,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);
@@ -102,7 +106,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);
@@ -110,7 +115,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 (
@@ -142,6 +149,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"]) {
@@ -160,6 +168,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/serializedAdapter.ts
 function isDriverError(err) {
@@ -449,6 +471,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++) {
@@ -523,7 +574,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: isStaleAfter(staleAfterRaw, now),
-    trustTier: deriveTrustTier(okf_verified)
+    trustTier: 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) {
@@ -944,12 +1001,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);
   }
@@ -963,6 +1022,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(", ");
@@ -970,8 +1030,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);
     }
@@ -991,10 +1052,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);
@@ -1202,6 +1264,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.
@@ -1634,9 +1787,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);
   }
@@ -1751,13 +1906,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) };
   }
@@ -1800,6 +1957,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
@@ -2248,6 +2420,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.
@@ -2256,30 +2440,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
       ]
     );
   }
@@ -2288,10 +2474,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.
@@ -2300,10 +2487,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.
@@ -2315,6 +2503,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.
@@ -2333,16 +2548,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;
   }
 };
 
@@ -2471,6 +2752,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
       )
@@ -2491,6 +2773,8 @@ var EdgeRepository = class extends BaseRepository {
       minConfidenceRank,
       ...opts.excludeSourceTypes,
       opts.excludeDrafts === true ? 1 : 0,
+      opts.live.t,
+      opts.live.t,
       opts.maxDepth,
       opts.maxNodes
     ];
@@ -2520,6 +2804,186 @@ function mapRowToEdge(row) {
   };
 }
 
+// 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
+    };
+  }
+};
+
 // src/prompts/ontology.ts
 var FACT_ONTOLOGY_FIELDS = `
 Each fact may optionally include:
@@ -2704,6 +3168,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",
@@ -2711,16 +3184,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)) };
   }
 };
 
@@ -3021,6 +3510,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(
@@ -3052,6 +3542,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,
@@ -3102,11 +3601,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,
@@ -3324,6 +3825,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,
@@ -3397,6 +3915,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
@@ -3715,10 +4245,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,
@@ -4009,7 +4540,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) {
@@ -4337,9 +4873,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(