@remnic/core 9.38.3 → 9.40.0

package/src/maintenance/projection-support.ts

@@ -6,7 +6,22 @@
  */
 
 import path from "node:path";
-import { openProjectionReadonly } from "../memory-projection-store.js";
+import {
+  openProjectionReadonly,
+  readProjectedEntityMentions,
+  readProjectedGovernanceRecord,
+  readProjectedNativeKnowledgeChunks,
+  type MemoryProjectionGovernanceAppliedActionRow,
+  type MemoryProjectionGovernanceReviewQueueRow,
+  type ProjectedEntityMentionRow,
+  type ProjectedNativeKnowledgeChunkRow,
+} from "../memory-projection-store.js";
+import {
+  isFrontmatterDerivedLifecycleEventType,
+  memoryLifecycleEventProjectionIdentity,
+} from "../memory-lifecycle-ledger-utils.js";
+import type { MemoryLifecycleEvent } from "../types.js";
+import type { BetterSqlite3Database } from "../runtime/better-sqlite.js";
 
 /** Read the projection meta rebuiltAt timestamp; null when absent/unopenable. */
 export function readProjectionRebuiltAt(memoryDir: string): string | null {
@@ -24,6 +39,172 @@ export function readProjectionRebuiltAt(memoryDir: string): string | null {
   }
 }
 
+/** Format projection age description string for fallback warning telemetry. */
+export function formatProjectionAge(rebuiltAt: string | null): string {
+  if (!rebuiltAt) return "projection never rebuilt";
+  const ageMs = Date.now() - Date.parse(rebuiltAt);
+  if (!Number.isFinite(ageMs)) return `projection rebuiltAt=${rebuiltAt}`;
+  const ageMin = Math.max(0, Math.round(ageMs / 60_000));
+  const age = ageMin >= 120 ? `${Math.round(ageMin / 60)}h` : `${ageMin}m`;
+  return `projection ${age} stale, last rebuilt ${rebuiltAt}`;
+}
+
+export interface ProjectionLifecycleLedgerHighWater {
+  eventCount: number;
+  sourceEventCount: number;
+}
+
+function readProjectionHighWaterFromDb(
+  db: BetterSqlite3Database,
+): ProjectionLifecycleLedgerHighWater | null {
+  const sourceRow = db.prepare(
+    "SELECT value FROM meta WHERE key = 'sourceLifecycleLedgerEventCount'",
+  ).get() as { value?: unknown } | undefined;
+  const projectedRow = db.prepare(
+    "SELECT value FROM meta WHERE key = 'projectedLifecycleLedgerEventCount'",
+  ).get() as { value?: unknown } | undefined;
+  if (
+    typeof sourceRow?.value !== "string"
+    || !/^\d+$/.test(sourceRow.value)
+    || typeof projectedRow?.value !== "string"
+    || !/^\d+$/.test(projectedRow.value)
+  ) return null;
+  const sourceEventCount = Number(sourceRow.value);
+  const eventCount = Number(projectedRow.value);
+  if (!Number.isSafeInteger(sourceEventCount) || !Number.isSafeInteger(eventCount)) return null;
+  return { eventCount, sourceEventCount };
+}
+
+export function readProjectionLifecycleLedgerHighWater(
+  memoryDir: string,
+): ProjectionLifecycleLedgerHighWater | null {
+  const db = openProjectionReadonly(memoryDir);
+  if (!db) return null;
+  try {
+    return readProjectionHighWaterFromDb(db);
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+export interface ProjectionLifecycleLedgerLagTracker {
+  highWater: ProjectionLifecycleLedgerHighWater;
+  record(event: MemoryLifecycleEvent): { unique: boolean; projected: boolean };
+  close(): void;
+}
+
+export function openProjectionLifecycleLedgerLagTracker(
+  memoryDir: string,
+): ProjectionLifecycleLedgerLagTracker | null {
+  const db = openProjectionReadonly(memoryDir);
+  if (!db) return null;
+  try {
+    const highWater = readProjectionHighWaterFromDb(db);
+    if (!highWater) {
+      db.close();
+      return null;
+    }
+    db.pragma("temp_store = FILE");
+    db.exec(`
+      CREATE TEMP TABLE projection_lag_current_identity (
+        identity TEXT PRIMARY KEY
+      ) WITHOUT ROWID;
+    `);
+    db.pragma("temp.cache_size = -1024");
+    const insertCurrent = db.prepare(
+      "INSERT OR IGNORE INTO projection_lag_current_identity(identity) VALUES (?)",
+    );
+    const findProjectedEvent = db.prepare(
+      "SELECT 1 FROM memory_timeline WHERE event_id = ? LIMIT 1",
+    );
+    const findProjectedFrontmatterEvent = db.prepare(`
+      SELECT 1
+      FROM memory_timeline
+      WHERE memory_id = ? AND event_type = ? AND timestamp = ?
+      LIMIT 1
+    `);
+    return {
+      highWater,
+      record(event) {
+        if (!event.memoryId.trim()) return { unique: false, projected: false };
+        const identity = memoryLifecycleEventProjectionIdentity(event);
+        const inserted = insertCurrent.run(identity);
+        if (inserted.changes === 0) return { unique: false, projected: false };
+        const projected = isFrontmatterDerivedLifecycleEventType(event.eventType)
+          ? findProjectedFrontmatterEvent.get(event.memoryId, event.eventType, event.timestamp)
+          : findProjectedEvent.get(event.eventId);
+        return { unique: true, projected: projected !== undefined };
+      },
+      close: () => db.close(),
+    };
+  } catch {
+    db.close();
+    return null;
+  }
+}
+/** Write the high-water ledger marker counts to projection meta store. */
+export function writeProjectionMetaHighWater(
+  insertMeta: { run: (key: string, value: string) => void },
+  sourceLifecycleLedgerEventCount: number,
+  timelineRows: MemoryLifecycleEvent[],
+): void {
+  insertMeta.run("sourceLifecycleLedgerEventCount", String(sourceLifecycleLedgerEventCount));
+  insertMeta.run(
+    "projectedLifecycleLedgerEventCount",
+    String(new Set(timelineRows.map(memoryLifecycleEventProjectionIdentity)).size),
+  );
+}
+
+export function readProjectedEntityMentionRows(
+  memoryDir: string,
+): { projectionExists: boolean; rows: ProjectedEntityMentionRow[] } {
+  const rows = readProjectedEntityMentions(memoryDir);
+  if (rows === null) return { projectionExists: false, rows: [] };
+  return { projectionExists: true, rows };
+}
+
+export function readProjectedNativeKnowledgeRows(
+  memoryDir: string,
+): { projectionExists: boolean; rows: ProjectedNativeKnowledgeChunkRow[] } {
+  const rows = readProjectedNativeKnowledgeChunks(memoryDir);
+  if (rows === null) return { projectionExists: false, rows: [] };
+  return { projectionExists: true, rows };
+}
+
+export function readProjectedGovernanceRows(memoryDir: string): {
+  projectionExists: boolean;
+  runId: string | null;
+  summary: unknown;
+  metrics: unknown;
+  reviewQueueRows: MemoryProjectionGovernanceReviewQueueRow[];
+  appliedActionRows: MemoryProjectionGovernanceAppliedActionRow[];
+  report: string;
+} {
+  const record = readProjectedGovernanceRecord(memoryDir);
+  if (record === null) {
+    return {
+      projectionExists: false,
+      runId: null,
+      summary: undefined,
+      metrics: undefined,
+      reviewQueueRows: [],
+      appliedActionRows: [],
+      report: "",
+    };
+  }
+  return {
+    projectionExists: true,
+    runId: record.runId,
+    summary: record.summary,
+    metrics: record.metrics,
+    reviewQueueRows: record.reviewQueueRows,
+    appliedActionRows: record.appliedActionRows,
+    report: record.report,
+  };
+}
+
 /**
  * Assert an optionally injected storage (e.g. the daemon's live unlocked
  * secure-store instance) is rooted at `memoryDir`, and hand it back. Shared
@@ -54,3 +235,13 @@ export interface SkippedDuplicateMemory {
 export interface SkippedBlankIdMemory {
   path: string;
 }
+export interface SkippedDuplicateTimelineEvent {
+  eventId: string;
+  keptPath: string;
+  skippedPath: string;
+}
+
+export interface SkippedBlankIdTimelineEvent {
+  eventId: string;
+  path: string;
+}

package/src/maintenance/rebuild-memory-lifecycle-ledger.ts

@@ -11,23 +11,14 @@ import {
   buildLifecycleEventsForMemory,
   compareMemoryLifecycleEvents,
   sortMemoryLifecycleEvents,
+  isFrontmatterDerivedLifecycleEventType,
+  memoryLifecycleEventProjectionIdentity,
   memoryLifecycleLedgerLockPath,
   MEMORY_LIFECYCLE_LEDGER_LOCK_STALE_MS,
 } from "../memory-lifecycle-ledger-utils.js";
 import { withHeldFileLock, type HeldFileLockOptions, type HeldFileLockController } from "../utils/serialize-mutations.js";
 import { probeEncryptedRegularFileHeader } from "../secure-store/secure-fs.js";
 
-/**
- * Event types `buildLifecycleEventsForMemory` reconstructs from frontmatter.
- * Everything else in the ledger is append-only history with no frontmatter
- * equivalent and must be carried over by a preserving rebuild (issue #1910).
- */
-const FRONTMATTER_DERIVED_EVENT_TYPES: Record<string, true> = {
-  created: true,
-  updated: true,
-  superseded: true,
-  archived: true,
-};
 
 export interface RebuildMemoryLifecycleLedgerOptions {
   memoryDir: string;
@@ -322,17 +313,15 @@ export async function rebuildMemoryLifecycleLedger(
       // retried append of the same logical event still collapses to one. Rows
       // that are not frontmatter-derived are append-only history with no
       // reconstruction — always carried over, deduped by eventId in the merge.
-      const contentKey = (event: MemoryLifecycleEvent): string =>
-        `${event.memoryId}\u0000${event.eventType}\u0000${event.timestamp}`;
-      const reconstructedKeys = new Set(events.map(contentKey));
+      const reconstructedKeys = new Set(events.map(memoryLifecycleEventProjectionIdentity));
       const racedFrontmatterByKey = new Map<string, MemoryLifecycleEvent>();
       const appendOnly: MemoryLifecycleEvent[] = [];
       for (const event of existing) {
-        if (!FRONTMATTER_DERIVED_EVENT_TYPES[event.eventType]) {
+        if (!isFrontmatterDerivedLifecycleEventType(event.eventType)) {
           appendOnly.push(event);
           continue;
         }
-        const key = contentKey(event);
+        const key = memoryLifecycleEventProjectionIdentity(event);
         if (reconstructedKeys.has(key)) continue; // collapsed into reconstruction
         if (!racedFrontmatterByKey.has(key)) racedFrontmatterByKey.set(key, event);
       }

package/src/maintenance/rebuild-memory-projection.ts

@@ -18,6 +18,7 @@ import {
   buildLifecycleEventsForMemory,
   inferMemoryStatus,
   MEMORY_LIFECYCLE_EVENT_SORT_ORDER,
+  memoryLifecycleEventProjectionIdentity,
   sortMemoryLifecycleEvents,
   toMemoryPathRel,
 } from "../memory-lifecycle-ledger-utils.js";
@@ -55,20 +56,26 @@ export interface RebuildMemoryProjectionOptions {
   updatedBefore?: string;
 }
 
-export type { SkippedBlankIdMemory, SkippedDuplicateMemory } from "./projection-support.js";
-import { assertInjectedStorageRooted } from "./projection-support.js";
-import type { SkippedBlankIdMemory, SkippedDuplicateMemory } from "./projection-support.js";
-
-export interface SkippedDuplicateTimelineEvent {
-  eventId: string;
-  keptPath: string;
-  skippedPath: string;
-}
+export type {
+  SkippedBlankIdMemory,
+  SkippedBlankIdTimelineEvent,
+  SkippedDuplicateMemory,
+  SkippedDuplicateTimelineEvent,
+} from "./projection-support.js";
+import {
+  assertInjectedStorageRooted,
+  readProjectedEntityMentionRows,
+  readProjectedGovernanceRows,
+  readProjectedNativeKnowledgeRows,
+  writeProjectionMetaHighWater,
+} from "./projection-support.js";
+import type {
+  SkippedBlankIdMemory,
+  SkippedBlankIdTimelineEvent,
+  SkippedDuplicateMemory,
+  SkippedDuplicateTimelineEvent,
+} from "./projection-support.js";
 
-export interface SkippedBlankIdTimelineEvent {
-  eventId: string;
-  path: string;
-}
 
 export interface RebuildMemoryProjectionResult {
   dryRun: boolean;
@@ -569,6 +576,7 @@ async function loadAuthoritativeProjectionSnapshot(options: {
     }
     | null;
   usedLifecycleLedger: boolean;
+  sourceLifecycleLedgerEventCount: number;
   scope: {
     updatedAfter: string | null;
     updatedBefore: string | null;
@@ -607,6 +615,9 @@ async function loadAuthoritativeProjectionSnapshot(options: {
   );
   const events = deduplicatedTimeline.events;
   const usedLifecycleLedger = timeline.usedLifecycleLedger;
+  const sourceLifecycleLedgerEventCount = new Set(
+    lifecycleEvents.map(memoryLifecycleEventProjectionIdentity),
+  ).size;
   const currentRows = projectionMemories.map((memory) => toCurrentStateRow(options.memoryDir, memory));
   const scope = normalizeProjectionScope(options);
   const scopedMemories = filterMemoriesForProjectionScope(projectionMemories, scope);
@@ -645,6 +656,7 @@ async function loadAuthoritativeProjectionSnapshot(options: {
     nativeKnowledgeRows,
     governance,
     usedLifecycleLedger,
+    sourceLifecycleLedgerEventCount,
     scope,
     skippedDuplicateMemories: selected.skippedDuplicateMemories,
     skippedBlankIdMemories: selected.skippedBlankIdMemories,
@@ -733,53 +745,6 @@ function readProjectedTimelineRows(
   }
 }
 
-function readProjectedEntityMentionRows(
-  memoryDir: string,
-): { projectionExists: boolean; rows: ProjectedEntityMentionRow[] } {
-  const rows = readProjectedEntityMentions(memoryDir);
-  if (rows === null) return { projectionExists: false, rows: [] };
-  return { projectionExists: true, rows };
-}
-
-function readProjectedNativeKnowledgeRows(
-  memoryDir: string,
-): { projectionExists: boolean; rows: ProjectedNativeKnowledgeChunkRow[] } {
-  const rows = readProjectedNativeKnowledgeChunks(memoryDir);
-  if (rows === null) return { projectionExists: false, rows: [] };
-  return { projectionExists: true, rows };
-}
-
-function readProjectedGovernanceRows(memoryDir: string): {
-  projectionExists: boolean;
-  runId: string | null;
-  summary: unknown;
-  metrics: unknown;
-  reviewQueueRows: MemoryProjectionGovernanceReviewQueueRow[];
-  appliedActionRows: MemoryProjectionGovernanceAppliedActionRow[];
-  report: string;
-} {
-  const record = readProjectedGovernanceRecord(memoryDir);
-  if (record === null) {
-    return {
-      projectionExists: false,
-      runId: null,
-      summary: undefined,
-      metrics: undefined,
-      reviewQueueRows: [],
-      appliedActionRows: [],
-      report: "",
-    };
-  }
-  return {
-    projectionExists: true,
-    runId: record.runId,
-    summary: record.summary,
-    metrics: record.metrics,
-    reviewQueueRows: record.reviewQueueRows,
-    appliedActionRows: record.appliedActionRows,
-    report: record.report,
-  };
-}
 
 function writeProjectionDb(
   dbPath: string,
@@ -790,6 +755,7 @@ function writeProjectionDb(
   nativeKnowledgeRows: ProjectedNativeKnowledgeChunkRow[],
   governance: Awaited<ReturnType<typeof loadLatestGovernanceProjection>>,
   usedLifecycleLedger: boolean,
+  sourceLifecycleLedgerEventCount: number,
 ): void {
   const db = openBetterSqlite3(dbPath);
   const memoryDir = path.dirname(path.dirname(dbPath));
@@ -800,6 +766,7 @@ function writeProjectionDb(
     insertMeta.run("schemaVersion", String(MEMORY_PROJECTION_SCHEMA_VERSION));
     insertMeta.run("rebuiltAt", nowIso);
     insertMeta.run("usedLifecycleLedger", usedLifecycleLedger ? "true" : "false");
+    writeProjectionMetaHighWater(insertMeta, sourceLifecycleLedgerEventCount, timelineRows);
     insertMeta.run("latestGovernanceRunId", governance?.runId ?? "");
 
     const insertCurrent = db.prepare(`
@@ -1161,6 +1128,7 @@ export async function rebuildMemoryProjection(
       nextNativeKnowledgeRows,
       nextGovernance,
       snapshot.usedLifecycleLedger,
+      snapshot.sourceLifecycleLedgerEventCount,
     );
     backupPath = await backupExistingProjection(options.memoryDir, outputPath, now);
     backupPath = await commitPreparedFileAtomically(tempPath, outputPath, backupPath);

package/src/memory-lifecycle-ledger-utils.ts

@@ -24,6 +24,27 @@ export const MEMORY_LIFECYCLE_EVENT_SORT_ORDER: Record<MemoryLifecycleEventType,
   archived: 10,
 };
 
+const FRONTMATTER_DERIVED_EVENT_TYPES: Record<string, true> = {
+  created: true,
+  updated: true,
+  superseded: true,
+  archived: true,
+};
+
+export function isFrontmatterDerivedLifecycleEventType(eventType: string): boolean {
+  return FRONTMATTER_DERIVED_EVENT_TYPES[eventType] === true;
+}
+
+export function memoryLifecycleEventProjectionIdentity(event: {
+  eventId: string;
+  memoryId: string;
+  eventType: string;
+  timestamp: string;
+}): string {
+  if (!isFrontmatterDerivedLifecycleEventType(event.eventType)) return `event\u0000${event.eventId}`;
+  return `frontmatter\u0000${event.memoryId}\u0000${event.eventType}\u0000${event.timestamp}`;
+}
+
 /**
  * Deterministic sort rank for a lifecycle event type. The ledger readers admit
  * any structurally valid row (permissive `eventType`, issue #1910), so an

package/src/orchestration/maintenance.test.ts

@@ -21,6 +21,7 @@ import path from "node:path";
 import { readProjectionRebuiltAt } from "../maintenance/projection-support.js";
 import { lstat, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
 
 import { MaintenanceScheduler } from "./maintenance.js";
 import {
@@ -2952,3 +2953,32 @@ test("scheduled projection rebuild skips when the projection was rebuilt within
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+
+test("maintenance tool request invokes the scheduled projection rebuild wiring (#2119)", async () => {
+  const memoryDir = await seedMemoryDirWithOneFact();
+  const scheduler = new MaintenanceScheduler({
+    config: fixtureConfig({
+      memoryDir,
+      projectionRebuildEnabled: true,
+      projectionRebuildIntervalMs: 6 * 60 * 60 * 1000,
+    }),
+    getQmd: () => ({ isAvailable: () => false }) as unknown as SearchBackend,
+    namespaceSearchRouter: {} as unknown as NamespaceSearchRouter,
+    namespaceCatalog: {} as unknown as NamespaceCatalog,
+  });
+  try {
+    scheduler.requestQmdMaintenanceForTool("test");
+    for (let attempt = 0; attempt < 100 && probeProjectionHealth(memoryDir).state === "absent"; attempt += 1) {
+      await delay(10);
+    }
+    assert.equal(
+      probeProjectionHealth(memoryDir).state,
+      "openable",
+      "the public maintenance request entrypoint must reach the projection rebuild",
+    );
+    assert.equal(readProjectedMemoryBrowse(memoryDir, { limit: 5, offset: 0 })?.total, 1);
+  } finally {
+    await scheduler.dispose();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/storage/memory-lifecycle-ledger-access.ts

@@ -1,7 +1,7 @@
 import { SecureStoreLockedError } from "../secure-store/secure-fs.js";
 import { isErrnoCode } from "../utils/errno.js";
 import { displayErrorDetail } from "../runtime/better-sqlite.js";
-import { rename, stat, unlink } from "node:fs/promises";
+import { lstat, rename, stat, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import type { MemoryLifecycleEvent } from "../types.js";
@@ -19,6 +19,15 @@ import {
   readMemoryLifecycleEventsFromLines,
   STATE_FILE_MAX_DECRYPT_BYTES,
 } from "./secure-line-reader.js";
+import { getMemoryProjectionPath } from "../memory-projection-store.js";
+import {
+  openProjectionLifecycleLedgerLagTracker,
+  type ProjectionLifecycleLedgerLagTracker,
+} from "../maintenance/projection-support.js";
+import {
+  type ProjectionLedgerLagTelemetry,
+  warnProjectionFallback,
+} from "../storage-guards.js";
 
 /** Reads a lifecycle-ledger file through the secure whole-file/plaintext line source. */
 export type LedgerSecureReader = (filePath: string) => Promise<string>;
@@ -190,6 +199,194 @@ export async function readBoundedLifecycleEventsFromLedger(
   }
 }
 
+export interface LifecycleLedgerProjectionLagRead {
+  events: MemoryLifecycleEvent[];
+  currentEventCount: number;
+  deltaEvents: number;
+  telemetryAvailable: boolean;
+}
+
+export async function readBoundedLifecycleEventsWithProjectionLag(
+  ledgerPath: string,
+  readSecureFile: LedgerSecureReader,
+  limit: number,
+  memoryId: string,
+  tracker: ProjectionLifecycleLedgerLagTracker,
+): Promise<LifecycleLedgerProjectionLagRead> {
+  let currentEventCount = 0;
+  let deltaEvents = 0;
+  let telemetryAvailable = true;
+  try {
+    const events = await readMemoryLifecycleEventsFromLines(
+      readMaybeEncryptedLines(
+        ledgerPath,
+        () => readSecureFile(ledgerPath),
+        STATE_FILE_MAX_DECRYPT_BYTES,
+      ),
+      Math.max(0, Math.floor(limit)),
+      memoryId,
+      compareMemoryLifecycleEvents,
+      (event) => {
+        if (!telemetryAvailable) return;
+        try {
+          const tracked = tracker.record(event);
+          if (!tracked.unique) return;
+          currentEventCount += 1;
+          if (!tracked.projected) deltaEvents += 1;
+        } catch {
+          telemetryAvailable = false;
+          currentEventCount = 0;
+          deltaEvents = 0;
+        }
+      },
+    );
+    return { events, currentEventCount, deltaEvents, telemetryAvailable };
+  } catch (err) {
+    if (err instanceof SecureStoreLockedError) throw err;
+    if (!isErrnoCode(err, "ENOENT")) throw err;
+    return { events: [], currentEventCount: 0, deltaEvents: 0, telemetryAvailable: false };
+  }
+}
+/**
+ * Probe filesystem identity stamps (dev:ino:size:mtimeMs:ctimeMs) for the
+ * projection database and lifecycle-ledger file. Returns `null` when either
+ * file is missing or unstatable so caller can disable the lag cache without
+ * throwing on transient I/O or permission errors (#2119 / review).
+ */
+export async function probeProjectionLedgerIdentities(
+  projectionPath: string,
+  ledgerPath: string,
+): Promise<{ projectionIdentity: string; ledgerIdentity: string } | null> {
+  try {
+    const [projectionIdentity, ledgerIdentity] = await Promise.all(
+      [projectionPath, ledgerPath].map(async (filePath) => {
+        try {
+          const file = await lstat(filePath);
+          return `${file.dev}:${file.ino}:${file.size}:${file.mtimeMs}:${file.ctimeMs}`;
+        } catch (err) {
+          if (isErrnoCode(err, "ENOENT")) return "absent";
+          // Probe failure: disable lag cache, do not block the primary timeline read (#2119 review).
+          return null;
+        }
+      }),
+    );
+    if (!projectionIdentity || !ledgerIdentity) return null;
+    return { projectionIdentity, ledgerIdentity };
+  } catch {
+    return null;
+  }
+}
+
+export interface ProjectionLedgerLagScan {
+  telemetry: ProjectionLedgerLagTelemetry | null;
+  events: MemoryLifecycleEvent[];
+  memoryId: string;
+  limit: number;
+}
+
+export class ProjectionLedgerLagManager {
+  private lagCache: {
+    generation: string;
+    telemetry: ProjectionLedgerLagTelemetry;
+  } | null = null;
+  private lagInFlight: {
+    generation: string;
+    scan: Promise<ProjectionLedgerLagScan>;
+  } | null = null;
+
+  async resolveTimelineWithLag(options: {
+    baseDir: string;
+    ledgerPath: string;
+    memoryId: string;
+    cappedLimit: number;
+    readSecureFile: LedgerSecureReader;
+    projectionAge: () => string;
+  }): Promise<MemoryLifecycleEvent[]> {
+    const { baseDir, ledgerPath, memoryId, cappedLimit, readSecureFile, projectionAge } = options;
+    const projectionPath = getMemoryProjectionPath(baseDir);
+    const identities = await probeProjectionLedgerIdentities(projectionPath, ledgerPath);
+
+    if (!identities) {
+      warnProjectionFallback(baseDir, "getMemoryTimeline", projectionAge);
+      return readBoundedLifecycleEventsFromLedger(ledgerPath, readSecureFile, cappedLimit, memoryId);
+    }
+
+    const { projectionIdentity, ledgerIdentity } = identities;
+    const generation = `${projectionIdentity}\0${ledgerIdentity}`;
+
+    const cachedLag = this.lagCache?.generation === generation
+      ? this.lagCache.telemetry
+      : null;
+    if (cachedLag) {
+      warnProjectionFallback(baseDir, "getMemoryTimeline", projectionAge, cachedLag);
+      return readBoundedLifecycleEventsFromLedger(ledgerPath, readSecureFile, cappedLimit, memoryId);
+    }
+
+    const inFlight = this.lagInFlight?.generation === generation
+      ? this.lagInFlight.scan
+      : null;
+    if (inFlight) {
+      const result = await inFlight;
+      if (result.telemetry) {
+        this.lagCache = { generation, telemetry: result.telemetry };
+      }
+      warnProjectionFallback(baseDir, "getMemoryTimeline", projectionAge, result.telemetry ?? undefined);
+      if (result.memoryId === memoryId && result.limit === cappedLimit) return result.events;
+      return readBoundedLifecycleEventsFromLedger(ledgerPath, readSecureFile, cappedLimit, memoryId);
+    }
+
+    const tracker = openProjectionLifecycleLedgerLagTracker(baseDir);
+    if (tracker) {
+      const highWater = tracker.highWater;
+      const scan = (async (): Promise<ProjectionLedgerLagScan> => {
+        try {
+          const fallback = await readBoundedLifecycleEventsWithProjectionLag(
+            ledgerPath,
+            readSecureFile,
+            cappedLimit,
+            memoryId,
+            tracker,
+          );
+          return {
+            telemetry: fallback.telemetryAvailable
+              ? {
+                  projectedEvents: highWater.eventCount,
+                  currentLedgerEvents: fallback.currentEventCount,
+                  deltaEvents: fallback.deltaEvents,
+                }
+              : null,
+            events: fallback.events,
+            memoryId,
+            limit: cappedLimit,
+          };
+        } finally {
+          try {
+            tracker.close();
+          } catch {
+            // Lag telemetry cleanup must not replace a successful ledger fallback.
+          }
+        }
+      })();
+      this.lagInFlight = { generation, scan };
+      try {
+        const result = await scan;
+        if (result.telemetry) {
+          this.lagCache = { generation, telemetry: result.telemetry };
+        }
+        warnProjectionFallback(baseDir, "getMemoryTimeline", projectionAge, result.telemetry ?? undefined);
+        return result.events;
+      } finally {
+        if (this.lagInFlight?.scan === scan) {
+          this.lagInFlight = null;
+        }
+      }
+    }
+
+    warnProjectionFallback(baseDir, "getMemoryTimeline", projectionAge);
+    return readBoundedLifecycleEventsFromLedger(ledgerPath, readSecureFile, cappedLimit, memoryId);
+  }
+}
+
 /**
  * Directory holding the durable pending-append spill for a lifecycle ledger
  * (#2033). When an append cannot acquire the ledger lock within its budget —