Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(doctor): timeline_history recount shares the run deadline (#7038)

garrytana3effdef4a19
diff --git a/src/commands/doctor/checks/timeline-history.ts b/src/commands/doctor/checks/timeline-history.ts
index 75777e2409..ae802f830b 100644
--- a/src/commands/doctor/checks/timeline-history.ts
+++ b/src/commands/doctor/checks/timeline-history.ts
@@ -7,9 +7,13 @@
* Bounded: pages carrying non-event timeline rows are classified in id order
* up to PAGE_CAP pages or TIME_BUDGET_MS per run. A run that stops early keeps
* its cursor in the config row `doctor.timeline_history.scan:<scope>` (#5821),
- * so successive doctor runs cover the whole scope. The ids of pages earlier
- * runs of the pass found are kept and recounted on every run, so a repair
- * between runs is seen and a pass that ends reports current counts. While a later pass is in progress, a clean
+ * so successive doctor runs cover the whole scope. The pages earlier runs of
+ * the pass found are kept with their counts and recounted within the same
+ * deadline (#7038): while the scan moves the recount gets at most half of it,
+ * and pages it does not reach go first next run. Once the scan reaches the
+ * end, the pages not yet recounted since then go first, then the rest. A pass
+ * ends only when the scan is done and every found page has been recounted, so
+ * a repair between runs is seen and a pass that ends reports current counts. While a later pass is in progress, a clean
* finished pass is trusted until a newer timeline row is written. A truncated
* run with neither is a lower bound and is never reported as clean.
*
@@ -30,8 +34,14 @@ const FOUND_CAP = 10_000;
interface PassTotals { materializable: number; unrenderable: number; affected: number; inspected: number; runs: number }
interface ScanState extends PassTotals {
cursor: number;
- /** Pages earlier runs of this pass found with rows to report (capped). */
+ /** Pages earlier runs of this pass found with rows to report (capped), in recount order. */
found?: number[];
+ /** Latest [materializable, unrenderable] per found page; up to FOUND_CAP entries in this one config row. A found id without one (older state) is kept until recounted. */
+ found_counts?: Record<string, [number, number]>;
+ /** The forward scan reached the end of the scope; only recounts remain. */
+ scan_done?: boolean;
+ /** Found pages not recounted since the scan reached the end; the pass ends when none is left. */
+ pending?: number[];
/** Highest timeline row id when the pass started; rows above it may be unscanned. */
started_max_entry: number;
last?: PassTotals & { max_entry: number; completed_at: string };
@@ -53,7 +63,7 @@ async function saveState(engine: BrainEngine, key: string, state: ScanState): Pr
try { await engine.setConfig(key, JSON.stringify(state)); } catch { /* best effort: the next run rescans from the start */ }
}
-export async function timelineHistoryCheck(engine: BrainEngine, sourceId?: string, opts: { pageCap?: number } = {}): Promise<Check> {
+export async function timelineHistoryCheck(engine: BrainEngine, sourceId?: string, opts: { pageCap?: number; timeBudgetMs?: number } = {}): Promise<Check> {
const name = 'timeline_history';
try {
const sources = sourceId ? [sourceId] : (await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE archived IS NOT TRUE')).map(r => r.id);
@@ -62,13 +72,29 @@ export async function timelineHistoryCheck(engine: BrainEngine, sourceId?: strin
const maxEntry = Number(max_entry);
const prior = await loadState(engine, key);
const state: ScanState = prior ?? { ...emptyTotals(), cursor: 0, started_max_entry: maxEntry };
- const scan = await scanTimelineHistory(engine, sources, state.cursor, { pages: opts.pageCap ?? PAGE_CAP, deadline: Date.now() + TIME_BUDGET_MS });
- const counted = [...await recountTimelinePages(engine, sources, state.found ?? []), ...scan.pages]
- .filter(p => p.materializable || p.unrenderable);
+ const budgetMs = opts.timeBudgetMs ?? TIME_BUDGET_MS;
+ const started = Date.now();
+ const found = (state.found ?? []).map(Number);
+ const pending = new Set(state.scan_done ? (state.pending ?? found).map(Number) : []);
+ const order = [...pending, ...found.filter(id => !pending.has(id))];
+ const recount = await recountTimelinePages(engine, sources, order, { deadline: started + (state.scan_done ? budgetMs : budgetMs / 2) });
+ const scan = state.scan_done ? { pages: [], inspected: 0, truncated: false, cursor: state.cursor }
+ : await scanTimelineHistory(engine, sources, state.cursor, { pages: opts.pageCap ?? PAGE_CAP, deadline: started + budgetMs });
+ const unreached = new Set(recount.unreached);
+ const counts: Record<string, [number, number]> = {};
+ for (const id of unreached) if (state.found_counts?.[id]) counts[id] = state.found_counts[id];
+ for (const p of [...recount.counted, ...scan.pages]) if (p.materializable || p.unrenderable) counts[Number(p.id)] = [p.materializable, p.unrenderable];
+ const nextFound = [...new Set([...unreached, ...order, ...scan.pages.map(p => Number(p.id))])]
+ .filter(id => unreached.has(id) || counts[id]).slice(0, FOUND_CAP);
+ const kept = new Set(nextFound);
+ const scanDone = state.scan_done === true || !scan.truncated;
+ const nextPending = scanDone ? recount.unreached.filter(id => (!state.scan_done || pending.has(id)) && kept.has(id)) : [];
+ const complete = scanDone && nextPending.length === 0;
+ const totals = nextFound.flatMap(id => counts[id] ? [counts[id]] : []);
const pass: PassTotals = {
- materializable: counted.reduce((n, p) => n + p.materializable, 0),
- unrenderable: counted.reduce((n, p) => n + p.unrenderable, 0),
- affected: counted.filter(p => p.materializable).length,
+ materializable: totals.reduce((n, c) => n + c[0], 0),
+ unrenderable: totals.reduce((n, c) => n + c[1], 0),
+ affected: totals.filter(c => c[0]).length,
inspected: state.inspected + scan.inspected,
runs: state.runs + 1,
};
@@ -77,7 +103,7 @@ export async function timelineHistoryCheck(engine: BrainEngine, sourceId?: strin
const segmentedDetails = segmented.pages ? { segmented_pages: segmented.pages, segmented_rows: segmented.rows, segmented_sample: segmented.sample } : {};
const segmentedNote = segmented.pages ? ` Also: ${segmentedTimelineNote(segmented)}` : '';
- if (!scan.truncated) {
+ if (complete) {
if (prior) {
await saveState(engine, key, { ...emptyTotals(), cursor: 0, started_max_entry: maxEntry,
last: { ...pass, max_entry: state.started_max_entry, completed_at: new Date().toISOString() } });
@@ -95,7 +121,8 @@ export async function timelineHistoryCheck(engine: BrainEngine, sourceId?: strin
: `Every timeline row has a bullet in its page (${pass.inspected} page(s) inspected${multiRun ? ` across ${pass.runs} doctor runs` : ''}).`) + segmentedNote };
}
- await saveState(engine, key, { ...state, ...pass, cursor: scan.cursor, found: counted.map(p => p.id).slice(0, FOUND_CAP) });
+ await saveState(engine, key, { ...state, ...pass, cursor: scan.cursor, found: nextFound,
+ found_counts: Object.fromEntries(nextFound.filter(id => counts[id]).map(id => [id, counts[id]])), scan_done: scanDone, pending: nextPending });
const details = { materializable_rows: pass.materializable, kept_unrenderable_rows: pass.unrenderable, pages_affected: pass.affected,
pages_inspected: pass.inspected, count: 'lower_bound', truncated: true, repair: 'timeline', pass_runs: pass.runs, resumes_after_page_id: scan.cursor, ...segmentedDetails };
const coverage = ` (this pass has inspected ${pass.inspected} page(s) over ${pass.runs} run(s) and resumes on the next doctor run; counts are a lower bound)`;
diff --git a/src/core/repair/timeline.ts b/src/core/repair/timeline.ts
index 4649192a68..67f73199ad 100644
--- a/src/core/repair/timeline.ts
+++ b/src/core/repair/timeline.ts
@@ -44,15 +44,26 @@ async function classifyTimelinePage(engine: BrainEngine, page: TimelinePage, sto
return pendingTimelineRows(engine, { ...page, timeline: page.timeline ?? '' }, await removedRowIds(engine, page, storedRows));
}
-/** Current counts for specific pages (doctor rechecks pages an earlier run of a multi-run pass found). */
-export async function recountTimelinePages(engine: BrainEngine, sourceIds: string[], ids: number[]) {
- if (ids.length === 0) return [];
+/**
+ * Current counts for specific pages (doctor rechecks pages an earlier run of a multi-run pass found), in the
+ * caller's order. Pages left when `budget.deadline` passes are returned in `unreached` without being classified;
+ * an id in neither list no longer names an inline page of the scope.
+ */
+export async function recountTimelinePages(engine: BrainEngine, sourceIds: string[], ids: number[], budget: { deadline?: number } = {}) {
+ const counted: Array<{ id: number; materializable: number; unrenderable: number }> = [];
+ const unreached: number[] = [];
+ if (ids.length === 0) return { counted, unreached };
const pages = await engine.executeRaw<TimelinePage>(`SELECT p.id,p.source_id,p.slug,p.compiled_truth,p.timeline FROM pages p
WHERE p.id = ANY($1::bigint[]) AND p.source_id=ANY($2::text[]) AND p.deleted_at IS NULL AND p.body_storage='inline'`, [ids, sourceIds]);
const stored = await storedRowsByPage(engine, pages);
- const counted = [];
- for (const page of pages) counted.push({ id: page.id, ...await classifyTimelinePage(engine, page, stored.get(Number(page.id))) });
- return counted;
+ const byId = new Map(pages.map(page => [Number(page.id), page]));
+ for (const id of ids) {
+ const page = byId.get(Number(id));
+ if (!page) continue;
+ if (budget.deadline !== undefined && Date.now() > budget.deadline) { unreached.push(Number(id)); continue; }
+ counted.push({ id: Number(id), ...await classifyTimelinePage(engine, page, stored.get(Number(id))) });
+ }
+ return { counted, unreached };
}
/**
diff --git a/test/doctor-timeline-history-cursor-5821.test.ts b/test/doctor-timeline-history-cursor-5821.test.ts
index 25adea3808..be372a7b4a 100644
--- a/test/doctor-timeline-history-cursor-5821.test.ts
+++ b/test/doctor-timeline-history-cursor-5821.test.ts
@@ -4,6 +4,11 @@
* timeline pages than the cap warned "scan incomplete" forever, even with
* nothing to repair. The cursor now persists between runs: successive runs
* finish a pass, a clean pass reports ok, and rows past the cap are found.
+ *
+ * #7038: the recount of pages earlier runs found had no deadline, so a large
+ * found list could keep a doctor run from ever saving its state. It now shares
+ * the run's deadline; a page it does not reach is carried, and a pass never
+ * ends with a found page left unrecounted.
*/
import { afterAll, beforeAll, beforeEach, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
@@ -80,3 +85,60 @@ test('a row repaired between runs of one pass is not counted when the pass ends'
const last = await run();
expect(last).toMatchObject({ status: 'ok', details: { count: 'exact', materializable_rows: 0, pages_inspected: PAGES } });
});
+
+const KEY = 'doctor.timeline_history.scan:default';
+const readState = async () => JSON.parse((await engine.getConfig(KEY))!);
+const pageId = async (i: number) => Number((await engine.executeRaw<{ id: number }>(`SELECT id FROM pages WHERE slug = $1 AND source_id = 'default'`, [`notes/timeline-${i}`]))[0].id);
+
+test('a run out of time keeps its cursor and every found page, and a later run still ends the pass', async () => {
+ for (let i = 0; i < PAGES; i++) await addDatabaseOnlyRow(i);
+ await run();
+ const saved = await readState();
+ expect(saved.found).toHaveLength(CAP);
+ const outOfTime = await timelineHistoryCheck(engine, 'default', { pageCap: CAP, timeBudgetMs: -1000 });
+ expect(outOfTime.details).toMatchObject({ count: 'lower_bound', truncated: true, pages_inspected: CAP });
+ const kept = await readState();
+ expect(kept.cursor).toBe(saved.cursor);
+ expect(new Set(kept.found)).toEqual(new Set(saved.found));
+ expect(kept.last).toBeUndefined();
+ const results = [];
+ for (let i = 0; i < 4 && results.at(-1)?.details?.count !== 'exact'; i++) results.push(await run());
+ expect(results.at(-1)).toMatchObject({ status: 'warn', details: { count: 'exact', materializable_rows: PAGES, pages_affected: PAGES, pages_inspected: PAGES } });
+});
+
+test('a finished scan does not end the pass while found pages wait for their recount', async () => {
+ for (let i = 0; i < PAGES; i++) await addDatabaseOnlyRow(i);
+ await timelineHistoryCheck(engine, 'default', { pageCap: 3 });
+ for (const i of [3, 4]) await engine.executeRaw(`DELETE FROM timeline_entries WHERE page_id = $1`, [await pageId(i)]);
+ const outOfTime = await timelineHistoryCheck(engine, 'default', { pageCap: 3, timeBudgetMs: -1000 });
+ expect(outOfTime.details).toMatchObject({ count: 'lower_bound', truncated: true });
+ const waiting = await readState();
+ expect(waiting.last).toBeUndefined();
+ expect(waiting.scan_done).toBe(true);
+ expect(new Set(waiting.pending)).toEqual(new Set([await pageId(0), await pageId(1), await pageId(2)]));
+ const done = await run();
+ expect(done).toMatchObject({ status: 'warn', details: { count: 'exact', materializable_rows: 3, pages_affected: 3, pages_inspected: 3 } });
+});
+
+test('found pages from an older state without counts are kept until recounted', async () => {
+ for (let i = 0; i < PAGES; i++) await addDatabaseOnlyRow(i);
+ const [{ max_entry }] = await engine.executeRaw<{ max_entry: number }>('SELECT max(id) AS max_entry FROM timeline_entries');
+ const found = [await pageId(0), await pageId(1)];
+ await engine.setConfig(KEY, JSON.stringify({ materializable: 2, unrenderable: 0, affected: 2, inspected: CAP, runs: 1, cursor: found[1], found, started_max_entry: Number(max_entry) }));
+ await timelineHistoryCheck(engine, 'default', { pageCap: CAP, timeBudgetMs: -1 });
+ expect([...(await readState()).found].sort()).toEqual([...found].sort());
+ let last;
+ for (let i = 0; i < 3; i++) { last = await run(); if ((last.details as { count?: string }).count === 'exact') break; }
+ expect(last).toMatchObject({ status: 'warn', details: { count: 'exact', materializable_rows: PAGES, pages_affected: PAGES, pages_inspected: PAGES } });
+});
+
+test('after the scan ends, found pages already recounted are recounted again when the budget allows', async () => {
+ for (let i = 0; i < 2; i++) await addDatabaseOnlyRow(i);
+ const [{ max_entry }] = await engine.executeRaw<{ max_entry: number }>('SELECT max(id) AS max_entry FROM timeline_entries');
+ const [p0, p1] = [await pageId(0), await pageId(1)];
+ await engine.setConfig(KEY, JSON.stringify({ materializable: 2, unrenderable: 0, affected: 2, inspected: PAGES, runs: 3, cursor: await pageId(PAGES - 1),
+ found: [p0, p1], found_counts: { [p0]: [1, 0], [p1]: [1, 0] }, scan_done: true, pending: [p0], started_max_entry: Number(max_entry) }));
+ await engine.executeRaw(`DELETE FROM timeline_entries WHERE source = 'legacy' AND page_id = $1`, [p1]);
+ const last = await run();
+ expect(last).toMatchObject({ status: 'warn', details: { count: 'exact', materializable_rows: 1, pages_affected: 1, pages_inspected: PAGES } });
+});