@remnic/core 9.6.18 → 9.6.19

package/src/orchestration/recall-internal.ts

@@ -36,6 +36,7 @@ import { StorageManager } from "../index.js";
 import { inferIntentFromText, planRecallMode } from "../intent.js";
 import { LcmEngine } from "../lcm/index.js";
 import { log } from "../logger.js";
+import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
 import { buildRetrievedMemoryProvenance } from "../memory-provenance.js";
 import { NamespaceCatalog } from "../namespaces/catalog.js";
 import { canReadNamespace, resolvePrincipal } from "../namespaces/principal.js";
@@ -64,6 +65,8 @@ import { isDisagreementPrompt } from "../signal.js";
 import { HourlySummarizer } from "../summarizer.js";
 import { buildTargetedFactRecallSection, shouldRecallTargetedFactEvidence } from "../targeted-fact-recall.js";
 import { shouldFilterSupersededFromRecall } from "../temporal-supersession.js";
+import { queryTemporalTimelineAsync } from "../temporal-index.js";
+import { buildTemporalTimelineRecallSection, type TemporalTimelineRecallItem } from "../temporal-timeline-recall.js";
 import { isValidAsOf } from "../temporal-validity.js";
 import { TmtBuilder } from "../tmt.js";
 import { TranscriptManager } from "../transcript.js";
@@ -3659,54 +3662,93 @@ export class RecallInternalCoordinator {
       }
     }
 
-    // 0e. Chronological event-order evidence. This recovers ordered user
-    // turns for prompts asking how topics unfolded across a conversation.
+    // 0e. Chronological event-order evidence. Prefer the ingest-time temporal
+    // index, which can safely merge event times across source sessions. Fall
+    // back to the legacy per-session LCM turn order when the index is absent.
     const eventOrderMaxChars =
       this.deps.getRecallSectionMaxChars("event-order") ??
       this.deps.config.eventOrderRecallMaxChars;
+    const eventOrderMaxItems =
+      this.deps.getRecallSectionNumber("event-order", "maxResults") ??
+      this.deps.config.eventOrderRecallMaxResults;
     if (
       this.deps.isSpecializedRecallSectionEnabled(
         "event-order",
         resolveRecallEnhancementCapabilities(this.deps.config).eventOrderRecall,
       ) &&
       eventOrderMaxChars !== 0 &&
-      this.deps.lcmEngine?.enabled &&
+      eventOrderMaxItems > 0 &&
       (recallMode as RecallPlanMode) !== "no_recall" &&
       shouldRecallEventOrderEvidence(retrievalQuery)
     ) {
       try {
-        // #1495 thread 3 + #1505 fallback unification: read across the ordered LCM
-        // read key set so a branch-scoped session reads its own chronological
-        // event-order evidence even at project/root scope. UNLIKE the relevance-
-        // ranked sections, event-order must NOT merge across keys: `turn_index` is
-        // LOCAL to each LCM `session_id` (`observe` numbers turns per session via
-        // `getMaxTurnIndex`), so interleaving two keys and sorting by `turn_index`
-        // would place an older project-scope turn after a newer branch-scope turn
-        // and misstate the chronology (#1505 codex P2). Like compressed-history,
-        // event-order is an inherently per-session ORDERED artifact, so it takes
-        // the highest-priority authorized key (primary overlay → project/root)
-        // that actually has chronological evidence — each key's timeline is
-        // internally consistent.
-        const eventOrderSection = await firstNonEmptyLcmRead(
-          (lcmSessionId) =>
-            buildEventOrderRecallSection({
-              engine: this.deps.lcmEngine,
-              sessionId: lcmSessionId,
-              query: retrievalQuery,
-              maxChars: eventOrderMaxChars,
-              maxItems:
-                this.deps.getRecallSectionNumber("event-order", "maxResults") ??
-                this.deps.config.eventOrderRecallMaxResults,
-              maxScanWindowTurns:
-                this.deps.getRecallSectionNumber("event-order", "maxTurns") ??
-                this.deps.config.eventOrderRecallScanWindowTurns,
-              maxScanWindowTokens:
-                this.deps.getRecallSectionNumber("event-order", "maxTokens") ??
-                this.deps.config.eventOrderRecallScanWindowTokens,
-            }),
-          (s) => !s,
-          "",
-        );
+        const maxItems = eventOrderMaxItems;
+        let eventOrderSection = "";
+        const timelineCandidateLimit = Math.min(256, Math.max(48, maxItems * 12));
+        const timeline = await queryTemporalTimelineAsync(this.deps.config.memoryDir, {
+          query: retrievalQuery,
+          limit: timelineCandidateLimit,
+        });
+        if (timeline) {
+          const timelineItems: TemporalTimelineRecallItem[] = [];
+          // Sequential reads keep file-descriptor pressure bounded. The index
+          // query above has already capped total reads deterministically.
+          for (const event of timeline) {
+            const namespace = this.deps.namespaceFromPath(event.path);
+            if (
+              resolveNamespaceCapabilities(this.deps.config).namespaces &&
+              !recallNamespaces.includes(namespace)
+            ) {
+              continue;
+            }
+            try {
+              const storage = resolveNamespaceCapabilities(this.deps.config).namespaces
+                ? await this.deps.storageRouter.storageFor(namespace)
+                : this.deps.storage;
+              const memory = await storage.readMemoryByPath(event.path);
+              if (!memory || !isActiveMemoryStatus(memory.frontmatter.status)) continue;
+              if (!isValidAsOf(memory.frontmatter, asOfMs ?? Date.now())) continue;
+              timelineItems.push({
+                memory,
+                eventAt: event.eventAt,
+                ...(event.observedAt ? { observedAt: event.observedAt } : {}),
+                ...(event.sessionKey ? { sessionKey: event.sessionKey } : {}),
+                ...(event.validUntil ? { validUntil: event.validUntil } : {}),
+              });
+            } catch {
+              continue;
+            }
+          }
+          eventOrderSection = buildTemporalTimelineRecallSection({
+            items: timelineItems,
+            query: retrievalQuery,
+            maxChars: eventOrderMaxChars,
+            maxItems,
+          });
+        }
+
+        // Legacy fallback: LCM turn indexes are local to one session, so keep
+        // first-non-empty semantics and never interleave them across sessions.
+        if (!eventOrderSection && this.deps.lcmEngine?.enabled) {
+          eventOrderSection = await firstNonEmptyLcmRead(
+            (lcmSessionId) =>
+              buildEventOrderRecallSection({
+                engine: this.deps.lcmEngine,
+                sessionId: lcmSessionId,
+                query: retrievalQuery,
+                maxChars: eventOrderMaxChars,
+                maxItems,
+                maxScanWindowTurns:
+                  this.deps.getRecallSectionNumber("event-order", "maxTurns") ??
+                  this.deps.config.eventOrderRecallScanWindowTurns,
+                maxScanWindowTokens:
+                  this.deps.getRecallSectionNumber("event-order", "maxTokens") ??
+                  this.deps.config.eventOrderRecallScanWindowTokens,
+              }),
+            (s) => !s,
+            "",
+          );
+        }
         if (eventOrderSection) {
           this.deps.appendRecallSection(
             sectionBuckets,

package/src/temporal-index.test.ts

@@ -7,9 +7,12 @@ import test from "node:test";
 import { setTimeout as delay } from "node:timers/promises";
 
 import {
+  deindexMemory,
   indexMemory,
+  indexesExist,
   queryByDateRangeAsync,
   queryByTagsAsync,
+  queryTemporalTimelineAsync,
   resolvePromptTagPrefilterAsync,
 } from "./temporal-index.js";
 
@@ -236,3 +239,157 @@ test("indexMemory replaces stale date and tag memberships for an existing path",
   assert.deepEqual(alphaMatches, new Set());
   assert.deepEqual(betaMatches, new Set([memoryPath]));
 });
+
+test("temporal timeline orders event time across sessions, not ingest order", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-order-"));
+  indexMemory(memoryDir, "/tmp/rome.md", "2026-07-02T00:00:00.000Z", [], {
+    validAt: "2026-05-10T00:00:00.000Z",
+    observedAt: "2026-07-02T00:00:00.000Z",
+    sessionKey: "session-b",
+  });
+  indexMemory(memoryDir, "/tmp/paris.md", "2026-07-03T00:00:00.000Z", [], {
+    validAt: "2026-03-04T00:00:00.000Z",
+    observedAt: "2026-07-03T00:00:00.000Z",
+    sessionKey: "session-a",
+  });
+
+  const timeline = await queryTemporalTimelineAsync(memoryDir);
+  assert.deepEqual(
+    timeline?.map(({ path, eventAt, sessionKey }) => ({ path, eventAt, sessionKey })),
+    [
+      { path: "/tmp/paris.md", eventAt: "2026-03-04T00:00:00.000Z", sessionKey: "session-a" },
+      { path: "/tmp/rome.md", eventAt: "2026-05-10T00:00:00.000Z", sessionKey: "session-b" },
+    ],
+  );
+});
+
+test("temporal timeline uses stable observation/path ordering for event-time ties", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-tie-"));
+  const eventAt = "2026-03-04T00:00:00.000Z";
+  indexMemory(memoryDir, "/tmp/z.md", eventAt, [], { validAt: eventAt, observedAt: "2026-07-03T00:00:00.000Z" });
+  indexMemory(memoryDir, "/tmp/a.md", eventAt, [], { validAt: eventAt, observedAt: "2026-07-02T00:00:00.000Z" });
+  indexMemory(memoryDir, "/tmp/b.md", eventAt, [], { validAt: eventAt, observedAt: "2026-07-02T00:00:00.000Z" });
+
+  const first = await queryTemporalTimelineAsync(memoryDir);
+  const second = await queryTemporalTimelineAsync(memoryDir);
+  assert.deepEqual(first?.map((entry) => entry.path), ["/tmp/a.md", "/tmp/b.md", "/tmp/z.md"]);
+  assert.deepEqual(second, first);
+});
+
+test("old or malformed temporal index shape is unavailable and requests rebuild", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-malformed-"));
+  await mkdir(join(memoryDir, "state"), { recursive: true });
+  await writeFile(
+    join(memoryDir, "state", "index_time.json"),
+    JSON.stringify({ version: 2, dates: {}, events: [] }),
+    "utf8",
+  );
+  await writeFile(
+    join(memoryDir, "state", "index_tags.json"),
+    JSON.stringify({ version: 2, tags: {}, aliases: {} }),
+    "utf8",
+  );
+
+  assert.equal(indexesExist(memoryDir), false);
+  assert.equal(await queryTemporalTimelineAsync(memoryDir), null);
+
+  await writeFile(
+    join(memoryDir, "state", "index_time.json"),
+    JSON.stringify({ version: 1, dates: {} }),
+    "utf8",
+  );
+  assert.equal(indexesExist(memoryDir), false);
+  assert.equal(await queryTemporalTimelineAsync(memoryDir), null);
+});
+
+test("deindex removes timeline rows so stale events cannot be recalled", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-delete-"));
+  const memoryPath = "/tmp/deleted.md";
+  const createdAt = "2026-03-04T00:00:00.000Z";
+  indexMemory(memoryDir, memoryPath, createdAt, ["trip"], { sessionKey: "session-a" });
+  deindexMemory(memoryDir, memoryPath, createdAt, ["trip"]);
+  assert.deepEqual(await queryTemporalTimelineAsync(memoryDir), []);
+});
+
+test("large temporal indexes return a bounded relevant oversample before memory reads", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-bounded-"));
+  for (let i = 0; i < 600; i += 1) {
+    const day = String((i % 28) + 1).padStart(2, "0");
+    indexMemory(
+      memoryDir,
+      `/tmp/event-${String(i).padStart(4, "0")}.md`,
+      `2026-03-${day}T00:00:00.000Z`,
+      [],
+      {
+        validAt: `2026-03-${day}T00:00:00.000Z`,
+        searchText: i === 317 ? "unique-marzipan-trip to Lisbon" : `routine event ${i}`,
+      },
+    );
+  }
+
+  const relevant = await queryTemporalTimelineAsync(memoryDir, {
+    query: "When was the marzipan trip to Lisbon?",
+    limit: 48,
+  });
+  assert.ok(relevant);
+  assert.ok(relevant.length <= 48);
+  assert.ok(relevant.some((entry) => entry.path.endsWith("event-0317.md")));
+
+  const generic = await queryTemporalTimelineAsync(memoryDir, {
+    query: "What happened first or last?",
+    limit: 48,
+  });
+  assert.equal(generic?.length, 48);
+  assert.equal(generic?.[0]?.eventAt, "2026-03-01T00:00:00.000Z");
+  assert.equal(generic?.at(-1)?.eventAt, "2026-03-28T00:00:00.000Z");
+});
+
+test("temporal timeline generic edge selection honors small and zero limits", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "remnic-temporal-timeline-small-limit-"));
+  for (let day = 1; day <= 4; day += 1) {
+    const timestamp = `2026-04-0${day}T00:00:00.000Z`;
+    indexMemory(memoryDir, `/tmp/edge-${day}.md`, timestamp, [], {
+      validAt: timestamp,
+      searchText: `unrelated event ${day}`,
+    });
+  }
+
+  const genericQuery = "What happened first or last?";
+  const limitOne = await queryTemporalTimelineAsync(memoryDir, {
+    query: genericQuery,
+    limit: 1,
+  });
+  assert.deepEqual(limitOne?.map((entry) => entry.path), ["/tmp/edge-1.md"]);
+
+  const limitTwo = await queryTemporalTimelineAsync(memoryDir, {
+    query: genericQuery,
+    limit: 2,
+  });
+  assert.deepEqual(limitTwo?.map((entry) => entry.path), [
+    "/tmp/edge-1.md",
+    "/tmp/edge-4.md",
+  ]);
+
+  assert.deepEqual(
+    await queryTemporalTimelineAsync(memoryDir, { query: genericQuery, limit: 0 }),
+    [],
+  );
+  assert.deepEqual(
+    await queryTemporalTimelineAsync(memoryDir, { query: genericQuery, limit: -3 }),
+    [],
+  );
+  assert.deepEqual(
+    (await queryTemporalTimelineAsync(memoryDir, {
+      query: genericQuery,
+      limit: 1.9,
+    }))?.map((entry) => entry.path),
+    ["/tmp/edge-1.md"],
+  );
+  assert.equal(
+    (await queryTemporalTimelineAsync(memoryDir, {
+      query: genericQuery,
+      limit: Number.POSITIVE_INFINITY,
+    }))?.length,
+    4,
+  );
+});

package/src/temporal-index.ts

@@ -27,6 +27,37 @@ export interface TemporalIndex {
   lastRebuildAt?: string;
   /** Map from YYYY-MM-DD → array of memory paths */
   dates: Record<string, string[]>;
+  /**
+   * Per-memory event-time rows used to reconstruct one chronology across
+   * source sessions. Keyed by path so an update replaces the prior row.
+   */
+  events: Record<string, TemporalIndexEvent>;
+}
+
+export interface TemporalIndexEvent {
+  path: string;
+  /** Event/valid time used for chronology. */
+  eventAt: string;
+  /** Ingest/source-observation time, when known. */
+  observedAt?: string;
+  /** Source session provenance, when the extractor recorded it. */
+  sessionKey?: string;
+  /** Exclusive validity end, when the event is bounded. */
+  validUntil?: string;
+  /** SHA-256 lexical fingerprints for bounded query-aware candidate selection. */
+  searchTokenHashes?: string[];
+}
+
+export interface TemporalIndexEntry {
+  path: string;
+  createdAt: string;
+  tags: string[];
+  validAt?: string;
+  observedAt?: string;
+  sessionKey?: string;
+  validUntil?: string;
+  /** Used only to derive token hashes; raw text is never persisted in the index. */
+  searchText?: string;
 }
 
 export interface TagIndex {
@@ -44,7 +75,7 @@ export interface TagNode {
   parents?: string[];
 }
 
-const INDEX_VERSION = 1;
+const INDEX_VERSION = 2;
 const TEMPORAL_INDEX_FILE = "index_time.json";
 const TAG_INDEX_FILE = "index_tags.json";
 const TAG_INDEX_VERSION = 2;
@@ -275,10 +306,28 @@ function writeJsonAtomic(filePath: string, data: unknown): void {
   }
 }
 
+function emptyTemporalIndex(): TemporalIndex {
+  return { version: INDEX_VERSION, dates: {}, events: {} };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeTemporalIndex(raw: TemporalIndex | null | undefined): TemporalIndex {
+  if (!isRecord(raw)) return emptyTemporalIndex();
+  return {
+    version: typeof raw.version === "number" ? raw.version : 0,
+    dates: isRecord(raw.dates) ? raw.dates as Record<string, string[]> : {},
+    events: isRecord(raw.events) ? raw.events as Record<string, TemporalIndexEvent> : {},
+    ...(typeof raw.lastRebuildAt === "string" ? { lastRebuildAt: raw.lastRebuildAt } : {}),
+  };
+}
+
 function updateTemporalIndex(memoryDir: string, update: (index: TemporalIndex) => void): void {
   const indexPath = temporalIndexPath(memoryDir);
   withIndexFileLock(indexPath, () => {
-    const index = readJsonSafe<TemporalIndex>(indexPath, { version: INDEX_VERSION, dates: {} });
+    const index = normalizeTemporalIndex(readJsonSafe<TemporalIndex>(indexPath, emptyTemporalIndex()));
     update(index);
     writeJsonAtomic(indexPath, index);
   });
@@ -305,6 +354,62 @@ function isoDateFromTimestamp(isoString: string): string {
   return isoString.slice(0, 10); // YYYY-MM-DD
 }
 
+function normalizedIsoTimestamp(value: string | undefined): string | undefined {
+  if (typeof value !== "string" || value.trim().length === 0) return undefined;
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return undefined;
+  try {
+    return new Date(ms).toISOString();
+  } catch {
+    return undefined;
+  }
+}
+
+function temporalEventFromEntry(entry: TemporalIndexEntry): TemporalIndexEvent {
+  const createdAt = normalizedIsoTimestamp(entry.createdAt) ?? new Date(0).toISOString();
+  const eventAt = normalizedIsoTimestamp(entry.validAt) ?? createdAt;
+  const observedAt = normalizedIsoTimestamp(entry.observedAt);
+  const validUntil = normalizedIsoTimestamp(entry.validUntil);
+  const sessionKey = typeof entry.sessionKey === "string" && entry.sessionKey.trim().length > 0
+    ? entry.sessionKey.replace(/[\u0000-\u001f\u007f]+/g, " ").trim()
+    : undefined;
+  const searchTokenHashes = temporalSearchTokenHashes(entry.searchText);
+  return {
+    path: entry.path,
+    eventAt,
+    ...(observedAt ? { observedAt } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+    ...(validUntil ? { validUntil } : {}),
+    ...(searchTokenHashes.length > 0 ? { searchTokenHashes } : {}),
+  };
+}
+
+function temporalSearchTokens(value: string | undefined): string[] {
+  if (!value) return [];
+  const tokens = value
+    .toLowerCase()
+    .match(/[\p{L}\p{N}][\p{L}\p{N}'_-]*/gu)
+    ?.filter((token) => token.length > 1) ?? [];
+  return [...new Set(tokens)].slice(0, 128);
+}
+
+function temporalSearchTokenHashes(value: string | undefined): string[] {
+  return temporalSearchTokens(value).map((token) =>
+    crypto.createHash("sha256").update(token).digest("hex"),
+  );
+}
+
+function compareTemporalIndexEvents(
+  left: TemporalIndexEvent,
+  right: TemporalIndexEvent,
+): number {
+  const byEvent = left.eventAt.localeCompare(right.eventAt);
+  if (byEvent !== 0) return byEvent;
+  const byObservation = (left.observedAt ?? "").localeCompare(right.observedAt ?? "");
+  if (byObservation !== 0) return byObservation;
+  return left.path.localeCompare(right.path);
+}
+
 function addPathToSet(record: Record<string, string[]>, key: string, p: string): void {
   if (!record[key]) {
     record[key] = [];
@@ -590,14 +695,27 @@ function promptContainsAlias(prompt: string, alias: string): boolean {
  * @param createdAt ISO timestamp of the memory's creation date
  * @param tags Array of tag strings from the memory's frontmatter
  */
-export function indexMemory(memoryDir: string, memoryPath: string, createdAt: string, tags: string[]): void {
+export function indexMemory(
+  memoryDir: string,
+  memoryPath: string,
+  createdAt: string,
+  tags: string[],
+  temporal: Omit<Partial<TemporalIndexEntry>, "path" | "createdAt" | "tags"> = {},
+): void {
   try {
     ensureStateDir(memoryDir);
 
     const dateKey = isoDateFromTimestamp(createdAt);
     updateTemporalIndex(memoryDir, (index) => {
+      index.version = INDEX_VERSION;
       removePathFromAllSets(index.dates, memoryPath);
       addPathToSet(index.dates, dateKey, memoryPath);
+      index.events[memoryPath] = temporalEventFromEntry({
+        path: memoryPath,
+        createdAt,
+        tags,
+        ...temporal,
+      });
     });
 
     updateTagIndex(memoryDir, (index) => {
@@ -623,6 +741,7 @@ export function deindexMemory(memoryDir: string, memoryPath: string, createdAt:
     const dateKey = isoDateFromTimestamp(createdAt);
     updateTemporalIndex(memoryDir, (index) => {
       removePathFromSet(index.dates, dateKey, memoryPath);
+      delete index.events[memoryPath];
     });
 
     updateTagIndex(memoryDir, (index) => {
@@ -649,6 +768,7 @@ export function clearIndexes(memoryDir: string): void {
       index.version = INDEX_VERSION;
       index.lastRebuildAt = undefined;
       index.dates = {};
+      index.events = {};
     });
     updateTagIndex(memoryDir, (index) => {
       index.version = TAG_INDEX_VERSION;
@@ -667,7 +787,9 @@ export function clearIndexes(memoryDir: string): void {
  */
 export function indexesExist(memoryDir: string): boolean {
   try {
-    return fs.existsSync(temporalIndexPath(memoryDir)) && fs.existsSync(tagIndexPath(memoryDir));
+    if (!fs.existsSync(tagIndexPath(memoryDir))) return false;
+    const raw = JSON.parse(fs.readFileSync(temporalIndexPath(memoryDir), "utf8")) as unknown;
+    return isRecord(raw) && raw.version === INDEX_VERSION && isRecord(raw.dates) && isRecord(raw.events);
   } catch {
     return false;
   }
@@ -679,17 +801,19 @@ export function indexesExist(memoryDir: string): boolean {
  */
 export function indexMemoriesBatch(
   memoryDir: string,
-  entries: Array<{ path: string; createdAt: string; tags: string[] }>
+  entries: TemporalIndexEntry[]
 ): void {
   if (entries.length === 0) return;
   try {
     ensureStateDir(memoryDir);
 
     updateTemporalIndex(memoryDir, (index) => {
+      index.version = INDEX_VERSION;
       for (const entry of entries) {
         const dateKey = isoDateFromTimestamp(entry.createdAt);
         removePathFromAllSets(index.dates, entry.path);
         addPathToSet(index.dates, dateKey, entry.path);
+        index.events[entry.path] = temporalEventFromEntry(entry);
       }
     });
 
@@ -738,9 +862,9 @@ export async function queryByDateRangeAsync(
     }
     let tIndex: TemporalIndex;
     try {
-      tIndex = JSON.parse(raw) as TemporalIndex;
+      tIndex = normalizeTemporalIndex(JSON.parse(raw) as TemporalIndex);
     } catch {
-      tIndex = { version: INDEX_VERSION, dates: {} };
+      tIndex = emptyTemporalIndex();
     }
     // toDate is exclusive (first day NOT included). Default: tomorrow so "all of today" is included.
     const end = toDate ?? new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
@@ -759,6 +883,86 @@ export async function queryByDateRangeAsync(
   }
 }
 
+/**
+ * Return the persisted event-time rows as one deterministic cross-session
+ * chronology. Equal event times are ordered by observation time, then path.
+ * Returns `null` when the index is missing, corrupt, or from an older schema;
+ * callers can then fail open to the pre-index recall path.
+ */
+export async function queryTemporalTimelineAsync(
+  memoryDir: string,
+  options: { query?: string; limit?: number } = {},
+): Promise<TemporalIndexEvent[] | null> {
+  try {
+    const raw = await fs.promises.readFile(temporalIndexPath(memoryDir), "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      !isRecord(parsed) ||
+      parsed.version !== INDEX_VERSION ||
+      !isRecord(parsed.dates) ||
+      !isRecord(parsed.events)
+    ) return null;
+    const index = normalizeTemporalIndex(parsed as unknown as TemporalIndex);
+    const chronology = Object.values(index.events)
+      .filter((event) =>
+        typeof event?.path === "string" &&
+        event.path.length > 0 &&
+        normalizedIsoTimestamp(event.eventAt) !== undefined
+      )
+      .map((event) => ({
+        path: event.path,
+        eventAt: normalizedIsoTimestamp(event.eventAt)!,
+        ...(normalizedIsoTimestamp(event.observedAt)
+          ? { observedAt: normalizedIsoTimestamp(event.observedAt) }
+          : {}),
+        ...(typeof event.sessionKey === "string" && event.sessionKey.trim().length > 0
+          ? { sessionKey: event.sessionKey.trim() }
+          : {}),
+        ...(normalizedIsoTimestamp(event.validUntil)
+          ? { validUntil: normalizedIsoTimestamp(event.validUntil) }
+          : {}),
+        ...(Array.isArray(event.searchTokenHashes)
+          ? { searchTokenHashes: event.searchTokenHashes.filter((hash) => typeof hash === "string") }
+          : {}),
+      }))
+      .sort(compareTemporalIndexEvents);
+    const requestedLimit = typeof options.limit === "number" && Number.isFinite(options.limit)
+      ? Math.max(0, Math.floor(options.limit))
+      : chronology.length;
+    if (requestedLimit === 0) return [];
+    if (chronology.length <= requestedLimit) return chronology;
+
+    const queryHashes = new Set(temporalSearchTokenHashes(options.query));
+    const scored = chronology.map((event) => ({
+      event,
+      score: (event.searchTokenHashes ?? []).reduce(
+        (sum, hash) => sum + (queryHashes.has(hash) ? 1 : 0),
+        0,
+      ),
+    }));
+    if (scored.some(({ score }) => score > 0)) {
+      return scored
+        .filter(({ score }) => score > 0)
+        .sort((left, right) => right.score - left.score || compareTemporalIndexEvents(left.event, right.event))
+        .slice(0, requestedLimit)
+        .map(({ event }) => event)
+        .sort(compareTemporalIndexEvents);
+    }
+
+    // No lexical match (legacy rows or generic "first/last" query): retain
+    // both chronology edges so earliest and latest questions remain answerable.
+    const earlyCount = Math.ceil(requestedLimit / 2);
+    const lateCount = requestedLimit - earlyCount;
+    const selected = [
+      ...chronology.slice(0, earlyCount),
+      ...(lateCount > 0 ? chronology.slice(-lateCount) : []),
+    ];
+    return selected.sort(compareTemporalIndexEvents);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Async version of queryByTags — uses non-blocking fs.promises.readFile
  * to avoid blocking the Node.js event loop.