cursedbelt-server 1.0.0

package/src/server/retention/sweeper.spec.ts

@@ -0,0 +1,321 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildRetentionFleetView } from "./fleet";
+import { DAY_MS, type RetentionDeclaration } from "./policy";
+import { readRetentionRegistry, setRetentionHomeForTests, writeRetentionOverride } from "./store";
+import { createRetentionSweeper } from "./sweeper";
+import { createSqliteTableTarget, type RetentionTarget } from "./target";
+
+const NOW = 1_800_000_000_000;
+
+const decl = (id: string, over: Partial<RetentionDeclaration> = {}): RetentionDeclaration => ({
+	app: "orch",
+	id,
+	label: id,
+	category: "run-log",
+	unit: "rows",
+	location: `orch.sqlite · ${id}`,
+	consequence: "past run outcomes",
+	...over,
+});
+
+let home: string;
+let db: Database;
+const logs: string[] = [];
+const log = (line: string): void => {
+	logs.push(line);
+};
+
+function seed(table: string, ages: number[]): void {
+	db.run(`CREATE TABLE ${table} (id INTEGER PRIMARY KEY, at INTEGER)`);
+	for (const days of ages) {
+		db.query(`INSERT INTO ${table} (at) VALUES ($at)`).run({ $at: NOW - days * DAY_MS } as never);
+	}
+}
+
+const target = (
+	id: string,
+	table: string,
+	over: Partial<RetentionDeclaration> = {},
+): RetentionTarget =>
+	createSqliteTableTarget({ db, declaration: decl(id, over), table, timeColumn: "at" });
+
+beforeEach(() => {
+	home = mkdtempSync(join(tmpdir(), "retention-sweeper-"));
+	setRetentionHomeForTests(home);
+	db = new Database(":memory:");
+	logs.length = 0;
+});
+afterEach(() => {
+	setRetentionHomeForTests(null);
+	db.close();
+	rmSync(home, { recursive: true, force: true });
+});
+
+describe("createRetentionSweeper", () => {
+	test("sweeps every resource and totals what it removed", () => {
+		seed("job_runs", [40, 30, 1]);
+		seed("check_runs", [90, 2]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs"), target("check-runs", "check_runs")],
+		});
+		const report = sweeper.sweepNow(NOW);
+		expect(report.totals.aged).toBe(3);
+		expect(report.resources.map((r) => r.key)).toEqual(["orch:job-runs", "orch:check-runs"]);
+	});
+
+	test("publishes measurements and the last sweep, so the UI works while the app is down", () => {
+		seed("job_runs", [40, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		sweeper.sweepNow(NOW);
+
+		const published = readRetentionRegistry(home)[0]?.resources[0];
+		expect(published?.measurement?.items).toBe(1);
+		expect(published?.lastSweep).toMatchObject({ aged: 1, overflow: 0 });
+		expect(published?.declaration.consequence).toBeTruthy();
+	});
+
+	test("the owner's override is what the sweep runs with", () => {
+		seed("job_runs", [40, 30, 20, 1]);
+		writeRetentionOverride("orch", "job-runs", { days: 25 }, { home });
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		// The 14-day default would have taken three; the override keeps the 20-day row.
+		expect(sweeper.sweepNow(NOW).totals.aged).toBe(2);
+		expect(db.query("SELECT COUNT(*) AS n FROM job_runs").get()).toEqual({ n: 2 });
+	});
+
+	test("a disabled override keeps everything and says so in the resolved policy", () => {
+		seed("job_runs", [400, 300]);
+		writeRetentionOverride("orch", "job-runs", { enabled: false }, { home });
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		const report = sweeper.sweepNow(NOW);
+		expect(report.totals.aged).toBe(0);
+		expect(report.resources[0]?.policy.enabled).toBe(false);
+	});
+
+	test("one broken resource never stops the others", () => {
+		seed("job_runs", [400]);
+		const exploding: RetentionTarget = {
+			declaration: decl("broken"),
+			measure: () => ({ items: 0 }),
+			preview: () => ({ aged: 0, overflow: 0 }),
+			sweep: () => {
+				throw new Error("database is locked");
+			},
+		};
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [exploding, target("job-runs", "job_runs")],
+		});
+		const report = sweeper.sweepNow(NOW);
+		expect(report.totals.errors).toBe(1);
+		expect(report.totals.aged).toBe(1); // the healthy one still ran
+		expect(report.resources.find((r) => r.key === "orch:broken")?.report.error).toMatch(/locked/);
+		expect(logs.some((l) => l.includes("sweep failed"))).toBe(true);
+	});
+
+	test("RETENTION_DISABLED still measures and publishes — a silent kill switch is a broken timer", () => {
+		seed("job_runs", [400, 300]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			disabled: true,
+			targets: [target("job-runs", "job_runs")],
+		});
+		expect(sweeper.sweepNow(NOW).totals.aged).toBe(0);
+		expect(readRetentionRegistry(home)[0]?.sweepDisabled).toBe(true);
+		expect(readRetentionRegistry(home)[0]?.resources[0]?.measurement?.items).toBe(2);
+		expect(sweeper.status().disabled).toBe(true);
+	});
+
+	test("an overflow is logged loudly — a bound that declines to bind is not a bound", () => {
+		seed("job_runs", [1, 1, 1, 1, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs", { defaultMaxItems: 2 })],
+		});
+		expect(sweeper.sweepNow(NOW).totals.overflow).toBe(3);
+		expect(logs.some((l) => l.includes("OVERFLOW"))).toBe(true);
+	});
+
+	test("a silent sweep stays silent — logging every no-op sweep trains people to ignore the log", () => {
+		seed("job_runs", [1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		sweeper.sweepNow(NOW);
+		expect(logs.filter((l) => l.includes("pruned"))).toHaveLength(0);
+	});
+
+	test("preview reports what WOULD go, and changes nothing", () => {
+		seed("job_runs", [40, 30, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		expect(sweeper.preview(NOW)).toEqual([
+			{ key: "orch:job-runs", policy: expect.objectContaining({ days: 14 }), aged: 2, overflow: 0 },
+		]);
+		expect(db.query("SELECT COUNT(*) AS n FROM job_runs").get()).toEqual({ n: 3 });
+	});
+
+	test("duplicate resource ids are refused at construction, not at the first sweep", () => {
+		seed("job_runs", [1]);
+		expect(() =>
+			createRetentionSweeper({
+				app: "orch",
+				home,
+				log,
+				targets: [target("job-runs", "job_runs"), target("job-runs", "job_runs")],
+			}),
+		).toThrow(/duplicate resource key/);
+	});
+
+	test("a malformed declaration is refused at construction", () => {
+		seed("job_runs", [1]);
+		expect(() =>
+			createRetentionSweeper({
+				app: "orch",
+				home,
+				log,
+				targets: [target("job-runs", "job_runs", { category: "saved-notes" as never })],
+			}),
+		).toThrow(/unknown category/);
+	});
+
+	test("the liveness kick sweeps when the timer has gone silent", () => {
+		seed("job_runs", [400]);
+		let clock = NOW;
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			intervalMs: 60_000,
+			targets: [target("job-runs", "job_runs")],
+			now: () => clock,
+		});
+		sweeper.start();
+		clock += 10 * 60_000; // the machine slept through several intervals
+		sweeper.ensureAlive();
+		sweeper.stop();
+		expect(logs.some((l) => l.includes("LIVENESS KICK"))).toBe(true);
+		expect(db.query("SELECT COUNT(*) AS n FROM job_runs").get()).toEqual({ n: 0 });
+	});
+
+	test("an overrides edit is noticed within a pulse, not within an interval", async () => {
+		// Otherwise the station's control appears to do nothing for most of a day.
+		seed("job_runs", [40, 30, 2]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			intervalMs: 10 * 60_000,
+			bootDelayMs: 10 * 60_000,
+			pulseMs: 10,
+			// The seeded ages are relative to NOW, so the sweep must read the same
+			// clock — the pulse itself compares real file mtimes and is unaffected.
+			now: () => NOW,
+			targets: [target("job-runs", "job_runs")],
+		});
+		sweeper.start();
+		writeRetentionOverride("orch", "job-runs", { days: 1 }, { home });
+		await Bun.sleep(120);
+		sweeper.stop();
+		expect(db.query("SELECT COUNT(*) AS n FROM job_runs").get()).toEqual({ n: 0 });
+		expect(logs.some((l) => l.includes("policy changed"))).toBe(true);
+	});
+
+	test("start publishes immediately — a dashboard blank after boot reads as broken", () => {
+		seed("job_runs", [1, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			intervalMs: 10 * 60_000,
+			bootDelayMs: 10 * 60_000,
+			targets: [target("job-runs", "job_runs")],
+		});
+		sweeper.start();
+		sweeper.stop();
+		expect(readRetentionRegistry(home)[0]?.resources[0]?.measurement?.items).toBe(2);
+	});
+});
+
+describe("buildRetentionFleetView", () => {
+	test("joins publications to overrides and resolves the SAME policy the sweep uses", () => {
+		seed("job_runs", [1, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("job-runs", "job_runs")],
+		});
+		sweeper.publish();
+		writeRetentionOverride("orch", "job-runs", { days: 30, note: "keeping a month" }, { home });
+
+		const view = buildRetentionFleetView({ home });
+		expect(view.rows).toHaveLength(1);
+		const row = view.rows[0];
+		expect(row?.policy.days).toBe(30);
+		expect(row?.policy.sources.days).toBe("override");
+		expect(row?.defaultDays).toBe(14);
+		expect(row?.override?.note).toBe("keeping a month");
+		expect(row?.category.label).toBe("Run log");
+		expect(view.totals).toMatchObject({ resources: 1, apps: 1, items: 2 });
+	});
+
+	test("an override with no declaration is surfaced as orphaned, not silently dropped", () => {
+		// An app renamed or retired a resource; the owner's setting is now inert and
+		// the UI has to be able to say so.
+		writeRetentionOverride("orch", "gone-away", { days: 30 }, { home });
+		const view = buildRetentionFleetView({ home });
+		expect(view.orphanedOverrides.map((o) => o.key)).toEqual(["orch:gone-away"]);
+	});
+
+	test("rows sort biggest-first — the view answers 'what is filling my disk'", () => {
+		seed("small", [1]);
+		seed("big", [1, 1, 1, 1]);
+		const sweeper = createRetentionSweeper({
+			app: "orch",
+			home,
+			log,
+			targets: [target("small", "small"), target("big", "big")],
+		});
+		sweeper.publish();
+		expect(buildRetentionFleetView({ home }).rows.map((r) => r.key)).toEqual([
+			"orch:big",
+			"orch:small",
+		]);
+	});
+});

package/src/server/retention/sweeper.ts

@@ -0,0 +1,367 @@
+/**
+ * The sweep RUNTIME — one timer per app that applies the fleet policy to every
+ * resource that app declared, publishes what it found, and never takes the app
+ * down when it fails.
+ *
+ * Generalized from `apps/orch/src/server/eventRetention.ts`, which had all of
+ * this already for exactly one table: the boot delay, the liveness kick, the
+ * never-throw sweep, the status readout. Those were not incidental — each is a
+ * failure that had already happened once — so they are kept verbatim in spirit
+ * and made to serve every resource in the fleet instead of one.
+ *
+ * ── Overrides take effect within a minute, not within an interval ───────────
+ * A sweep runs every 6 hours by default. If the owner's change in the station UI
+ * only applied on that cadence, the control would appear to do nothing for most
+ * of a day — the "button that visibly does nothing" failure this fleet has
+ * already paid for elsewhere. So a light PULSE timer stats `overrides.json` once
+ * a minute and sweeps early when it has changed since the last applied read.
+ * One `stat` a minute is free; a UI whose settings look inert is not.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import type { EffectiveRetentionPolicy } from "./policy";
+import { assertRetentionDeclaration, resolveRetentionPolicy, retentionKey } from "./policy";
+import type { PublishedResource, RetentionSweepReport } from "./store";
+import { publishRetention, readRetentionOverrides, resolveRetentionHome } from "./store";
+import type { RetentionTarget } from "./target";
+
+/** Default cadence. Diagnostic data is not urgent; four sweeps a day is plenty. */
+export const DEFAULT_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** How often to notice an overrides edit. */
+export const OVERRIDES_PULSE_MS = 60_000;
+
+export interface ResourceOutcome {
+	key: string;
+	policy: EffectiveRetentionPolicy;
+	report: RetentionSweepReport;
+}
+
+export interface RetentionRunReport {
+	at: number;
+	resources: ResourceOutcome[];
+	/** Totals across every resource, for one honest log line. */
+	totals: { aged: number; overflow: number; bytesFreed: number; errors: number };
+}
+
+export interface RetentionSweeper {
+	start(): void;
+	stop(): void;
+	/** A supervisor's liveness poke — rebuild a timer lost to sleep/hibernate. */
+	ensureAlive(): void;
+	/** Run one sweep synchronously. Never throws. */
+	sweepNow(now?: number): RetentionRunReport;
+	/** Measure and republish without deleting anything — what the UI reads. */
+	publish(): void;
+	/** What each resource WOULD remove right now, under the current policy. */
+	preview(
+		now?: number,
+	): Array<{ key: string; policy: EffectiveRetentionPolicy; aged: number; overflow: number }>;
+	status(): {
+		app: string;
+		home: string;
+		disabled: boolean;
+		lastRun: RetentionRunReport | null;
+		nextRunAt: number | null;
+		lastError: string | null;
+	};
+}
+
+export interface CreateRetentionSweeperOptions {
+	app: string;
+	targets: RetentionTarget[];
+	intervalMs?: number;
+	bootDelayMs?: number;
+	/** How often to notice an overrides edit. Injectable so tests need not wait a minute. */
+	pulseMs?: number;
+	/** `local` / `prod` / `dev` — informational, shown in the UI. */
+	instance?: string;
+	/**
+	 * Kill switch. `RETENTION_DISABLED=1` in the app's environment stops every
+	 * sweep while still publishing measurements, so the UI shows the sizes AND
+	 * says plainly that nothing is being pruned. A silent kill switch would be
+	 * indistinguishable from a broken timer.
+	 */
+	disabled?: boolean;
+	home?: string;
+	log?: (line: string) => void;
+	now?: () => number;
+}
+
+const formatBytes = (bytes: number): string => {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB"];
+	let value = bytes / 1024;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit++;
+	}
+	return `${value.toFixed(1)} ${units[unit]}`;
+};
+
+export function createRetentionSweeper(options: CreateRetentionSweeperOptions): RetentionSweeper {
+	const { app, targets } = options;
+	const intervalMs = options.intervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+	const bootDelayMs = options.bootDelayMs ?? 60_000;
+	const home = options.home ?? resolveRetentionHome();
+	const log = options.log ?? ((line: string) => console.log(`[${app}] ${line}`));
+	const now = options.now ?? (() => Date.now());
+	const disabled = options.disabled ?? process.env.RETENTION_DISABLED === "1";
+
+	// Fail at construction, where the stack names the app — not at the first sweep
+	// six hours later, in a daemon nobody is watching. A duplicate key is the
+	// nastier of the two: two resources sharing one override would let the owner
+	// change a number and silently govern the wrong thing.
+	const seenKeys = new Set<string>();
+	for (const target of targets) {
+		assertRetentionDeclaration(target.declaration);
+		const key = retentionKey(target.declaration.app, target.declaration.id);
+		if (seenKeys.has(key)) {
+			throw new Error(
+				`retention: duplicate resource key "${key}" — ids must be unique within an app`,
+			);
+		}
+		seenKeys.add(key);
+	}
+
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	let pulse: ReturnType<typeof setInterval> | null = null;
+	let stopped = true;
+	let nextRunAt: number | null = null;
+	let lastRun: RetentionRunReport | null = null;
+	let lastError: string | null = null;
+	let lastBeatAt = now();
+	let appliedOverridesAt = 0;
+
+	const overridesFile = join(home, "overrides.json");
+
+	function policiesNow(): Map<string, EffectiveRetentionPolicy> {
+		const file = readRetentionOverrides(home);
+		appliedOverridesAt = Math.max(appliedOverridesAt, file.updatedAt ?? 0);
+		const resolved = new Map<string, EffectiveRetentionPolicy>();
+		for (const target of targets) {
+			const declaration = target.declaration;
+			const policy = resolveRetentionPolicy(
+				declaration,
+				file.overrides[`${declaration.app}:${declaration.id}`],
+			);
+			resolved.set(policy.key, policy);
+		}
+		return resolved;
+	}
+
+	/** Measure every resource and write the publication the station UI reads. */
+	function publish(lastReports?: Map<string, RetentionSweepReport>): void {
+		const resources: PublishedResource[] = [];
+		for (const target of targets) {
+			const key = `${target.declaration.app}:${target.declaration.id}`;
+			let measurement: PublishedResource["measurement"];
+			try {
+				measurement = target.measure();
+			} catch (error) {
+				log(
+					`⚠️  retention: could not measure ${key} — ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+			const previous = lastRun?.resources.find((r) => r.key === key)?.report;
+			const lastSweep = lastReports?.get(key) ?? previous;
+			resources.push({
+				declaration: target.declaration,
+				...(measurement ? { measurement } : {}),
+				...(lastSweep ? { lastSweep } : {}),
+			});
+		}
+		publishRetention(
+			{
+				app,
+				...(options.instance ? { instance: options.instance } : {}),
+				...(disabled ? { sweepDisabled: true } : {}),
+				resources,
+			},
+			{ home, log },
+		);
+	}
+
+	function sweepNow(at = now()): RetentionRunReport {
+		lastBeatAt = at;
+		const outcomes: ResourceOutcome[] = [];
+		const totals = { aged: 0, overflow: 0, bytesFreed: 0, errors: 0 };
+		const reports = new Map<string, RetentionSweepReport>();
+		let policies: Map<string, EffectiveRetentionPolicy>;
+		try {
+			policies = policiesNow();
+		} catch (error) {
+			// A malformed declaration must not wedge the timer — report and skip.
+			lastError = error instanceof Error ? error.message : String(error);
+			log(`⚠️  retention: cannot resolve policies — ${lastError}`);
+			const report: RetentionRunReport = { at, resources: [], totals: { ...totals, errors: 1 } };
+			lastRun = report;
+			return report;
+		}
+
+		for (const target of targets) {
+			const key = `${target.declaration.app}:${target.declaration.id}`;
+			const policy = policies.get(key);
+			if (!policy) continue;
+			let report: RetentionSweepReport;
+			if (disabled) {
+				report = { at, aged: 0, overflow: 0 };
+			} else {
+				try {
+					report = target.sweep(policy, at);
+				} catch (error) {
+					// A busy/locked database is a transient the next sweep clears; one
+					// broken resource must never stop the others.
+					const message = error instanceof Error ? error.message : String(error);
+					report = { at, aged: 0, overflow: 0, error: message };
+					totals.errors++;
+					log(`⚠️  retention: ${key} sweep failed — ${message}`);
+				}
+			}
+			totals.aged += report.aged;
+			totals.overflow += report.overflow;
+			totals.bytesFreed += report.bytesFreed ?? 0;
+			reports.set(key, report);
+			outcomes.push({ key, policy, report });
+
+			// An archiving resource that refuses to trim looks EXACTLY like one with
+			// nothing to do — same zeros, same silence — so the refusal has to be the
+			// noisy case. It means the archive's collector has stopped, which is a
+			// disk problem on its way to becoming a data problem.
+			if (report.blocked) {
+				log(`⚠️  retention: ${key} did NOT trim — ${report.blocked}`);
+			}
+			if (report.overflow > 0) {
+				log(
+					`⚠️  retention: ${key} OVERFLOW — ${report.overflow} oldest item(s) dropped to hold it at ` +
+						`${policy.maxItems}. These went regardless of the age rule: something is writing far ` +
+						"faster than expected. A bound that declines to bind is not a bound.",
+				);
+			}
+		}
+
+		const report: RetentionRunReport = { at, resources: outcomes, totals };
+		lastRun = report;
+		if (totals.errors === 0) lastError = null;
+		// Silence is the healthy steady state — log only a sweep that changed something.
+		if (totals.aged > 0 || totals.overflow > 0) {
+			// "pruned" and "archived" are not the same event and must not read as one:
+			// the first is data the owner agreed to lose, the second is data that moved.
+			const archived = outcomes.reduce((sum, o) => sum + (o.report.archived ?? 0), 0);
+			log(
+				`retention: pruned ${totals.aged + totals.overflow - archived} item(s)` +
+					(archived > 0 ? `, archived ${archived}` : "") +
+					(totals.bytesFreed > 0 ? `, ${formatBytes(totals.bytesFreed)} reclaimed` : "") +
+					` across ${outcomes.filter((o) => o.report.aged + o.report.overflow > 0).length} resource(s)`,
+			);
+		}
+		publish(reports);
+		return report;
+	}
+
+	function schedule(delayMs = intervalMs): void {
+		if (stopped) return;
+		if (timer) clearTimeout(timer);
+		nextRunAt = now() + delayMs;
+		timer = setTimeout(() => {
+			timer = null;
+			sweepNow();
+			schedule();
+		}, delayMs);
+		// Unref'd for the same reason the pulse is, and it was the one that mattered:
+		// a 6-hour `setTimeout` is a 6-hour reason for a process not to exit. Every
+		// caller that owns a drain calls `stop()`, but `apps/vault` deliberately has
+		// no signal handler (launchd restarts it), and without this a SIGTERM there
+		// would hang until the timer fired or the supervisor lost patience and
+		// SIGKILLed — which is exactly how a WAL gets left half-closed. Housekeeping
+		// must never be the last thing holding a process open.
+		(timer as { unref?: () => void }).unref?.();
+	}
+
+	/** Notice an overrides edit made by the station and act on it promptly. */
+	function checkOverrides(): void {
+		if (stopped) return;
+		try {
+			const mtime = statSync(overridesFile).mtimeMs;
+			if (mtime > appliedOverridesAt) {
+				appliedOverridesAt = mtime;
+				log("retention: policy changed — sweeping now");
+				sweepNow();
+				schedule();
+			}
+		} catch {
+			// No overrides file yet is the normal case on a fresh machine.
+		}
+	}
+
+	return {
+		start() {
+			if (!stopped) return;
+			stopped = false;
+			lastBeatAt = now();
+			// Publish immediately so the UI has the fleet's sizes without waiting for
+			// the first sweep — a dashboard that is blank for a minute after boot
+			// reads as broken.
+			try {
+				publish();
+			} catch (error) {
+				log(
+					`⚠️  retention: initial publish failed — ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+			try {
+				appliedOverridesAt = statSync(overridesFile).mtimeMs;
+			} catch {
+				appliedOverridesAt = 0;
+			}
+			schedule(Math.min(bootDelayMs, intervalMs));
+			pulse = setInterval(checkOverrides, options.pulseMs ?? OVERRIDES_PULSE_MS);
+			// Never hold the process open for housekeeping.
+			(pulse as { unref?: () => void }).unref?.();
+		},
+		stop() {
+			stopped = true;
+			if (timer) clearTimeout(timer);
+			if (pulse) clearInterval(pulse);
+			timer = null;
+			pulse = null;
+			nextRunAt = null;
+		},
+		ensureAlive() {
+			if (stopped) return;
+			// ~3 missed intervals, floored so a fast test cadence is not declared
+			// wedged the moment it is a beat late — the watchdog's shape.
+			const staleAfterMs = Math.max(intervalMs * 3, 90_000);
+			if (now() - lastBeatAt <= staleAfterMs) return;
+			log(
+				"⚠️  retention: LIVENESS KICK — sweep timer silent (system sleep/hibernate?) — sweeping now",
+			);
+			sweepNow();
+			schedule();
+		},
+		sweepNow,
+		publish: () => publish(),
+		preview(at = now()) {
+			const policies = policiesNow();
+			const rows: Array<{
+				key: string;
+				policy: EffectiveRetentionPolicy;
+				aged: number;
+				overflow: number;
+			}> = [];
+			for (const target of targets) {
+				const key = `${target.declaration.app}:${target.declaration.id}`;
+				const policy = policies.get(key);
+				if (!policy) continue;
+				try {
+					const { aged, overflow } = target.preview(policy, at);
+					rows.push({ key, policy, aged, overflow });
+				} catch {
+					rows.push({ key, policy, aged: 0, overflow: 0 });
+				}
+			}
+			return rows;
+		},
+		status: () => ({ app, home, disabled, lastRun, nextRunAt, lastError }),
+	};
+}