cursedbelt 2.7.0 → 3.0.0

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

@@ -1,321 +0,0 @@
-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

@@ -1,367 +0,0 @@
-/**
- * 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 }),
-	};
-}