cursedbelt 0.0.0 → 2.3.0

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

@@ -0,0 +1,181 @@
+/**
+ * The archive's contract is a promise about ORDER: the bytes are provably on
+ * disk before anything is deleted. Every test here is that promise from a
+ * different angle, and the load-bearing ones are the failures — a sink that
+ * silently succeeded when it had not written would be indistinguishable from one
+ * that worked, right up until the day it mattered.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveAppDataHome } from "../paths/appDataHome";
+import {
+	archiveStamp,
+	createJsonlArchive,
+	resolveArchiveHome,
+	verifyArchive,
+	type ArchiveHome,
+} from "./archive";
+
+const temps: string[] = [];
+const tmp = (): string => {
+	const dir = mkdtempSync(join(tmpdir(), "cb-archive-"));
+	temps.push(dir);
+	return dir;
+};
+afterEach(() => {
+	for (const dir of temps.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+const home = (dir: string, terminal = true): ArchiveHome => ({ dir, terminal });
+const AT = Date.UTC(2026, 7, 25, 11, 42, 33);
+
+describe("createJsonlArchive", () => {
+	test("a sealed segment is on disk, one JSON row per line, and named for its resource", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir) });
+		const segment = sink.write([{ seq: 1, kind: "item.upsert" }, { seq: 2, kind: "tag.set" }], AT);
+
+		expect(segment.file).toBe(`sync-history-${archiveStamp(new Date(AT))}.jsonl`);
+		expect(segment.rows).toBe(2);
+		const body = readFileSync(segment.path, "utf8");
+		expect(body.split("\n").filter(Boolean).map((l) => JSON.parse(l))).toEqual([
+			{ seq: 1, kind: "item.upsert" },
+			{ seq: 2, kind: "tag.set" },
+		]);
+	});
+
+	test("every segment is catalogued in an APPEND-only index, and verifyArchive re-proves them", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir) });
+		sink.write([{ seq: 1 }], AT);
+		sink.write([{ seq: 2 }, { seq: 3 }], AT + 60_000);
+
+		expect(verifyArchive(dir)).toEqual({ segments: 2, rows: 3, bytes: expect.any(Number), bad: [] });
+	});
+
+	test("🔴 corruption after the fact is REPORTED — an archive nobody can check is a belief", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir) });
+		const segment = sink.write([{ seq: 1 }], AT);
+		writeFileSync(segment.path, '{"seq":99}\n');
+
+		const report = verifyArchive(dir);
+		expect(report.bad).toEqual([`${segment.file}: sha256 mismatch`]);
+	});
+
+	test("a collected segment reads as absent rather than as corruption", () => {
+		// The healthy steady state on a deployed box: the Mac pulled it and removed
+		// the box's copy. Calling that corruption would make the normal case alarming.
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir, false) });
+		const segment = sink.write([{ seq: 1 }], AT);
+		rmSync(segment.path);
+		expect(verifyArchive(dir).bad).toEqual([`${segment.file}: absent (collected, or lost)`]);
+	});
+
+	test("🔴 an unwritable home THROWS — the caller must never read that as 'nothing to archive'", () => {
+		const dir = tmp();
+		const locked = join(dir, "locked");
+		mkdirSync(locked);
+		chmodSync(locked, 0o500);
+		const sink = createJsonlArchive({
+			app: "notes",
+			resource: "sync-history",
+			home: home(join(locked, "archive")),
+		});
+		expect(() => sink.write([{ seq: 1 }], AT)).toThrow();
+		chmodSync(locked, 0o700);
+	});
+
+	test("an empty segment is refused — a sweep with nothing to move must not seal a file", () => {
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(tmp()) });
+		expect(() => sink.write([], AT)).toThrow(/empty segment/);
+	});
+
+	test("no half-written segment is ever visible: the temp file does not survive", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir) });
+		sink.write([{ seq: 1 }], AT);
+		const strays = readFileSync(join(dir, "index.jsonl"), "utf8");
+		expect(strays).toContain("sync-history");
+		expect(existsSync(join(dir, `sync-history-${archiveStamp(new Date(AT))}.jsonl.${process.pid}.tmp`))).toBe(
+			false,
+		);
+	});
+});
+
+describe("pendingBytes — the staleness signal a deployed box can actually observe", () => {
+	test("a TERMINAL archive owes nobody anything, however large it gets", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir, true) });
+		sink.write(Array.from({ length: 500 }, (_, i) => ({ seq: i })), AT);
+		expect(sink.pendingBytes()).toBe(0);
+	});
+
+	test("a STAGED archive counts every uncollected segment, and forgets one that was taken", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir, false) });
+		const first = sink.write([{ seq: 1 }], AT);
+		const second = sink.write([{ seq: 2 }], AT + 60_000);
+		expect(sink.pendingBytes()).toBe(first.bytes + second.bytes);
+
+		rmSync(first.path); // the Mac pulled it
+		expect(sink.pendingBytes()).toBe(second.bytes);
+	});
+
+	test("the catalogue is not counted as pending — it is not history, it is the list", () => {
+		const dir = tmp();
+		const sink = createJsonlArchive({ app: "notes", resource: "sync-history", home: home(dir, false) });
+		const only = sink.write([{ seq: 1 }], AT);
+		expect(sink.pendingBytes()).toBe(only.bytes);
+	});
+});
+
+describe("resolveArchiveHome", () => {
+	test("the shared OS-convention home is TERMINAL — the archive simply grows there", () => {
+		const root = tmp();
+		const conventional = resolveAppDataHome({ env: { HOME: root } });
+		mkdirSync(conventional, { recursive: true });
+		const resolved = resolveArchiveHome("notes", { HOME: root });
+		expect(resolved).toEqual({
+			dir: join(conventional, "cursed-satellites", "archive", "notes"),
+			terminal: true,
+		});
+	});
+
+	test("APP_DATA_HOME is honored before the convention, and before it exists", () => {
+		const configured = join(tmp(), "managed");
+		expect(resolveArchiveHome("notes", { APP_DATA_HOME: configured })).toEqual({
+			dir: join(configured, "cursed-satellites", "archive", "notes"),
+			terminal: true,
+		});
+	});
+
+	/**
+	 * 🔴 Up to 2026-09-13 this resolved a hardcoded dotfolder in the owner's home —
+	 * in a PUBLISHED package. Asserted on the output, so it still holds if the
+	 * folder comes back through a variable.
+	 */
+	test("resolves nothing from a previous generation, whatever the env says", () => {
+		const root = tmp();
+		const resolved = resolveArchiveHome("notes", { HOME: root, APP_MANAGED_HOME: "/nowhere/inherited" });
+		expect(resolved.dir).not.toContain("app-managed");
+		expect(resolved.dir).not.toContain("/nowhere/inherited");
+	});
+
+	test("🔴 a deployed box falls back to the data dir and is STAGED — something must collect it", () => {
+		const root = tmp(); // no shared data home, which is every deployed box
+		const dataDir = join(tmp(), "data");
+		mkdirSync(dataDir, { recursive: true });
+		expect(resolveArchiveHome("notes", { HOME: root, APP_DATA_DIR: dataDir })).toEqual({
+			dir: join(dataDir, "archive"),
+			terminal: false,
+		});
+	});
+
+	test("an app key that could escape its directory is refused", () => {
+		expect(() => resolveArchiveHome("notes/../etc")).toThrow(/lower-kebab/);
+	});
+});

package/src/server/retention/archive.ts

@@ -0,0 +1,353 @@
+/**
+ * The ARCHIVE half of `archived-history` — where the rows go before they are
+ * allowed to leave the instance.
+ *
+ * ── The ordering rule IS the safety argument, and this fleet has broken it ───
+ * prod's `diskGuard.sh` rule 1 deletes the oldest `VACUUM INTO` sqlite backups
+ * to free space, and its own comment calls those files "NOT regenerable". A
+ * cleanup routine that runs before the copy is data loss wearing housekeeping's
+ * name, and it is the exact failure this module exists to make impossible. So:
+ *
+ *   1. serialize the rows,
+ *   2. write them to a NEW file, fsync it,
+ *   3. RE-READ that file off the disk and prove it — byte length, sha256, line
+ *      count, and that every line parses back to an object,
+ *   4. only then may the caller delete those rows.
+ *
+ * `write()` throws rather than returning a failure, because the one thing a
+ * caller must never be able to do is treat "the archive did not happen" as
+ * "nothing to delete". A throw ends the sweep for that resource with the rows
+ * still in the table, which is the correct outcome every time.
+ *
+ * ── A segment per sweep, never an appended file ─────────────────────────────
+ * "Append-only" is a property of the DIRECTORY here: each sweep seals its own
+ * `<resource>-<stamp>.jsonl` and nothing is ever rewritten. That is not a style
+ * choice. On a deployed box the archive is a WAY-STATION — the Mac's
+ * `backups:pull-prod` copies segments down and removes the box's copy — and a
+ * collector that scp'd a file the app was still appending to would take a
+ * prefix and then delete the rest. A sealed file cannot be half a file.
+ *
+ * ── Terminal vs staged, and the staleness refusal ───────────────────────────
+ * On a workstation the archive is home: `<app-data-home>/cursed-satellites/
+ * archive/<app>/`, it is `terminal`, and it simply grows. The home is
+ * CONFIGURATION ({@link resolveAppDataHome}) — `$APP_DATA_HOME`, else the OS's own
+ * convention — never a folder this library invented in somebody's home; that was
+ * the published defect fixed 2026-09-13. On a deployed box nothing outside the
+ * app's own data dir is writable, so it resolves to `$APP_DATA_DIR/archive` and
+ * is `staged` — something else has to come and get it. That distinction is what lets the
+ * sweeper honor "refuse to trim if the last successful pull is stale" using a
+ * fact the box can actually observe: how many bytes of sealed segments are still
+ * sitting there uncollected. If the collector stops, the archive fills to its
+ * budget and the trim STOPS — bounded archive, complete table — rather than the
+ * table trimming into an archive nobody is taking away.
+ */
+import { createHash } from "node:crypto";
+import {
+	appendFileSync,
+	closeSync,
+	existsSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+	writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome } from "../paths/appDataHome";
+
+/** One sealed archive file. */
+export interface ArchiveSegment {
+	/** Absolute path on this machine. */
+	path: string;
+	/** Basename — what a collector and the index line name it by. */
+	file: string;
+	rows: number;
+	bytes: number;
+	sha256: string;
+	at: number;
+}
+
+export interface ArchiveSink {
+	/** Where segments are written. */
+	readonly dir: string;
+	/** True when THIS machine is the archive's final home (no collector is owed). */
+	readonly terminal: boolean;
+	/**
+	 * Bytes of sealed segments still waiting for a collector. Always 0 when
+	 * `terminal` — a home archive is never "pending", it is the archive.
+	 */
+	pendingBytes(): number;
+	/**
+	 * Seal one segment, proven on disk. THROWS if it cannot prove it: the caller
+	 * treats that as "these rows stay in the table".
+	 */
+	write(records: ReadonlyArray<Record<string, unknown>>, at: number): ArchiveSegment;
+}
+
+/** The default budget of uncollected archive on a staged (deployed-box) home.
+ *  Generous next to the tables it governs — notes' whole `ops` log is ~15 MB —
+ *  and small next to a 6.7 GB root. Reached only if the collector has stopped. */
+export const DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES = 64 * 1024 * 1024;
+
+const SAFE_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/** `20260825-114233` — sortable, second-resolution, and the same shape the
+ *  fleet's dated backup dirs already use, so one eye reads both. */
+export function archiveStamp(date: Date): string {
+	const p = (n: number, w = 2) => String(n).padStart(w, "0");
+	return (
+		`${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}-` +
+		`${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}`
+	);
+}
+
+export interface ArchiveHome {
+	dir: string;
+	terminal: boolean;
+}
+
+/** Can we create and write inside this directory? Probed, never assumed —
+ *  the same reasoning as `resolveRetentionHome`, and the same failure it
+ *  prevents: a writer that silently EROFS-es every time. */
+function isUsable(dir: string): boolean {
+	try {
+		mkdirSync(dir, { recursive: true });
+		const probe = join(dir, ".write-probe");
+		writeFileSync(probe, "");
+		rmSync(probe, { force: true });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Where this app's archive lives on THIS machine, and whether the machine keeps
+ * it.
+ *
+ * `<app-data-home>/cursed-satellites/archive/<app>/`, reached through the same env
+ * ladder the retention home uses, so a test, a container and a deployed box each
+ * land somewhere writable rather than somewhere assumed.
+ */
+export function resolveArchiveHome(
+	app: string,
+	env: Record<string, string | undefined> = process.env,
+): ArchiveHome {
+	if (!SAFE_NAME.test(app)) throw new Error(`archive: app key "${app}" must be lower-kebab`);
+	const candidates: ArchiveHome[] = [];
+	if (env.RETENTION_ARCHIVE_HOME) {
+		candidates.push({ dir: join(env.RETENTION_ARCHIVE_HOME, app), terminal: true });
+	}
+	// An explicitly CONFIGURED home is used whether or not it exists yet — the
+	// operator naming it is the statement that it is the right place.
+	const configured = env[APP_DATA_HOME_ENV]?.trim();
+	if (configured) {
+		candidates.push({
+			dir: join(configured, "cursed-satellites", "archive", app),
+			terminal: true,
+		});
+	}
+	const conventional = resolveAppDataHome({ env });
+	// The OS convention is only PREFERRED when it is already there: creating it on
+	// a deployed box would strand the archive where no collector looks.
+	if (!configured && existsSync(conventional)) {
+		candidates.push({
+			dir: join(conventional, "cursed-satellites", "archive", app),
+			terminal: true,
+		});
+	}
+	// A deployed box: only the app's own data dir is writable under
+	// `ProtectSystem=strict`, and something else has to come and collect it.
+	if (env.APP_DATA_DIR) candidates.push({ dir: join(env.APP_DATA_DIR, "archive"), terminal: false });
+
+	for (const candidate of candidates) {
+		if (isUsable(candidate.dir)) return candidate;
+	}
+	// Nothing writable. Return the conventional path and let `write()` throw when
+	// it is actually used — which, by this module's contract, means nothing is
+	// deleted. Never a boot failure.
+	return { dir: join(conventional, "cursed-satellites", "archive", app), terminal: true };
+}
+
+export interface JsonlArchiveOptions {
+	app: string;
+	/** Stable, app-scoped resource id — the segment name's prefix. */
+	resource: string;
+	/** Overrides the resolved home. Tests and callers that already resolved it. */
+	home?: ArchiveHome;
+	env?: Record<string, string | undefined>;
+}
+
+/**
+ * The fleet's archive sink: newline-delimited JSON segments plus an append-only
+ * `index.jsonl` naming every segment ever sealed here.
+ *
+ * The index is what makes the archive answerable without reading gigabytes —
+ * "what is in here, how many rows, and does it still hash the same" — and it is
+ * appended rather than rewritten so a crash mid-write can cost at most the last
+ * line, never the catalogue.
+ */
+export function createJsonlArchive(options: JsonlArchiveOptions): ArchiveSink {
+	const { app, resource } = options;
+	if (!SAFE_NAME.test(resource)) {
+		throw new Error(`archive: resource id "${resource}" must be lower-kebab`);
+	}
+	const home = options.home ?? resolveArchiveHome(app, options.env);
+	const dir = home.dir;
+	const terminal = home.terminal;
+	const indexPath = join(dir, "index.jsonl");
+
+	return {
+		dir,
+		terminal,
+
+		pendingBytes() {
+			if (terminal) return 0;
+			let total = 0;
+			let names: string[];
+			try {
+				names = readdirSync(dir);
+			} catch {
+				return 0; // not created yet — nothing is owed
+			}
+			for (const name of names) {
+				if (!name.endsWith(".jsonl") || name === "index.jsonl") continue;
+				try {
+					total += statSync(join(dir, name)).size;
+				} catch {
+					// vanished between readdir and stat — the collector took it
+				}
+			}
+			return total;
+		},
+
+		write(records, at) {
+			if (records.length === 0) throw new Error("archive: refusing to seal an empty segment");
+			const body = `${records.map((row) => JSON.stringify(row)).join("\n")}\n`;
+			const bytes = Buffer.byteLength(body);
+			const sha256 = createHash("sha256").update(body).digest("hex");
+			const file = `${resource}-${archiveStamp(new Date(at))}.jsonl`;
+			const path = join(dir, file);
+			const tmp = `${path}.${process.pid}.tmp`;
+
+			mkdirSync(dir, { recursive: true });
+
+			// Write + fsync THE FILE. Without the fsync the bytes can be in the page
+			// cache while the rows are already gone from a database that fsyncs its
+			// own WAL — a power cut between the two loses exactly the rows this
+			// module exists to keep.
+			const fd = openSync(tmp, "w");
+			try {
+				writeSync(fd, body);
+				fsyncSync(fd);
+			} finally {
+				closeSync(fd);
+			}
+
+			// Prove it, off the disk, before anything is deleted. Re-reading is the
+			// only check that covers a short write, a full disk that reported
+			// success, and a filesystem that lied.
+			let readBack: string;
+			try {
+				readBack = readFileSync(tmp, "utf8");
+			} catch (error) {
+				rmSync(tmp, { force: true });
+				throw new Error(
+					`archive: could not read back ${tmp} — ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+			const verify = (ok: boolean, what: string): void => {
+				if (ok) return;
+				rmSync(tmp, { force: true });
+				throw new Error(`archive: ${file} failed verification (${what}) — nothing was deleted`);
+			};
+			verify(Buffer.byteLength(readBack) === bytes, `expected ${bytes} bytes`);
+			verify(createHash("sha256").update(readBack).digest("hex") === sha256, "sha256 mismatch");
+			const lines = readBack.split("\n").filter((line) => line.length > 0);
+			verify(lines.length === records.length, `expected ${records.length} rows, read ${lines.length}`);
+			for (const line of lines) {
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					verify(false, "a row did not parse back");
+					return undefined as never;
+				}
+				verify(typeof parsed === "object" && parsed !== null, "a row read back as a non-object");
+			}
+
+			// Sealed. `rename` inside one directory is atomic on every filesystem
+			// this fleet runs on, so a collector never sees a partial segment.
+			renameSync(tmp, path);
+
+			const segment: ArchiveSegment = { path, file, rows: records.length, bytes, sha256, at };
+			try {
+				appendFileSync(
+					indexPath,
+					`${JSON.stringify({ app, resource, ...segment, path: undefined, file })}\n`,
+				);
+			} catch {
+				// The catalogue is a convenience; the segment is the archive. A failed
+				// index append must never make a sealed segment look unsealed and send
+				// the same rows through again.
+			}
+			return segment;
+		},
+	};
+}
+
+/**
+ * Re-verify every segment in an archive directory against the sha256 the index
+ * recorded — the answer to "is this archive still real?" without a restore.
+ *
+ * Exists because an archive nobody can check is a belief, and this whole
+ * category is a promise that the rows still exist somewhere.
+ */
+export function verifyArchive(dir: string): {
+	segments: number;
+	rows: number;
+	bytes: number;
+	bad: string[];
+} {
+	const result = { segments: 0, rows: 0, bytes: 0, bad: [] as string[] };
+	let index: string;
+	try {
+		index = readFileSync(join(dir, "index.jsonl"), "utf8");
+	} catch {
+		return result;
+	}
+	for (const line of index.split("\n")) {
+		if (!line.trim()) continue;
+		let entry: { file?: string; rows?: number; bytes?: number; sha256?: string };
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			result.bad.push(`unparseable index line: ${line.slice(0, 80)}`);
+			continue;
+		}
+		if (!entry.file || !entry.sha256) continue;
+		result.segments++;
+		const path = join(dir, entry.file);
+		let body: string;
+		try {
+			body = readFileSync(path, "utf8");
+		} catch {
+			// On a STAGED archive a collected segment is the healthy outcome, so
+			// absence is reported as a fact rather than as corruption.
+			result.bad.push(`${entry.file}: absent (collected, or lost)`);
+			continue;
+		}
+		if (createHash("sha256").update(body).digest("hex") !== entry.sha256) {
+			result.bad.push(`${entry.file}: sha256 mismatch`);
+			continue;
+		}
+		result.rows += entry.rows ?? 0;
+		result.bytes += entry.bytes ?? 0;
+	}
+	return result;
+}

package/src/server/retention/fleet.ts

@@ -0,0 +1,104 @@
+/**
+ * The read model behind the station's Retention view: every app's published
+ * resources joined to the owner's overrides, with the effective policy resolved
+ * by the SAME function the sweeps use.
+ *
+ * That last point is the whole reason this is a shared function rather than a
+ * few lines in the station's route handler. A UI that computes "effective days"
+ * its own way eventually disagrees with the sweeper, and the disagreement shows
+ * up as data that vanished earlier than the screen said it would — which is the
+ * one failure mode that would make the owner stop trusting the control.
+ */
+import type { EffectiveRetentionPolicy, RetentionOverride } from "./policy";
+import { RETENTION_CATEGORIES, resolveRetentionPolicy } from "./policy";
+import type { PublishedResource, RetentionPublication } from "./store";
+import { readRetentionOverrides, readRetentionRegistry, resolveRetentionHome } from "./store";
+
+export interface RetentionFleetRow extends PublishedResource {
+	key: string;
+	app: string;
+	policy: EffectiveRetentionPolicy;
+	override?: RetentionOverride;
+	/** The category's description, denormalized so the UI needs no second lookup. */
+	category: { label: string; defaultDays: number; summary: string };
+	/** Default days for this resource before any override — what "Reset" returns to. */
+	defaultDays: number;
+	/** The publishing app's last heartbeat, so the UI can label a stale row. */
+	publishedAt: number;
+	instance?: string;
+	sweepDisabled?: boolean;
+}
+
+export interface RetentionFleetView {
+	home: string;
+	updatedAt: number;
+	rows: RetentionFleetRow[];
+	totals: { resources: number; apps: number; items: number; bytes: number };
+	/** Overrides with no matching declaration — an app renamed or retired a resource. */
+	orphanedOverrides: Array<{ key: string; override: RetentionOverride }>;
+}
+
+export function buildRetentionFleetView(options: { home?: string } = {}): RetentionFleetView {
+	const home = options.home ?? resolveRetentionHome();
+	const publications: RetentionPublication[] = readRetentionRegistry(home);
+	const overridesFile = readRetentionOverrides(home);
+	const rows: RetentionFleetRow[] = [];
+	const claimed = new Set<string>();
+
+	for (const publication of publications) {
+		for (const resource of publication.resources) {
+			const declaration = resource.declaration;
+			if (!declaration || typeof declaration.app !== "string") continue;
+			const key = `${declaration.app}:${declaration.id}`;
+			const override = overridesFile.overrides[key];
+			let policy: EffectiveRetentionPolicy;
+			try {
+				policy = resolveRetentionPolicy(declaration, override);
+			} catch {
+				// A publication written by an older/newer app version than this reader
+				// understands is skipped rather than allowed to break the whole view.
+				continue;
+			}
+			claimed.add(key);
+			const category = RETENTION_CATEGORIES[declaration.category];
+			rows.push({
+				...resource,
+				key,
+				app: declaration.app,
+				policy,
+				...(override ? { override } : {}),
+				category,
+				defaultDays: declaration.defaultDays ?? category.defaultDays,
+				publishedAt: publication.publishedAt,
+				...(publication.instance ? { instance: publication.instance } : {}),
+				...(publication.sweepDisabled ? { sweepDisabled: true } : {}),
+			});
+		}
+	}
+
+	// Biggest first: the view exists to answer "what is filling my disk".
+	rows.sort((a, b) => {
+		const bytes = (b.measurement?.bytes ?? 0) - (a.measurement?.bytes ?? 0);
+		if (bytes !== 0) return bytes;
+		const items = (b.measurement?.items ?? 0) - (a.measurement?.items ?? 0);
+		if (items !== 0) return items;
+		return a.key.localeCompare(b.key);
+	});
+
+	const orphanedOverrides = Object.entries(overridesFile.overrides)
+		.filter(([key]) => !claimed.has(key))
+		.map(([key, override]) => ({ key, override }));
+
+	return {
+		home,
+		updatedAt: overridesFile.updatedAt,
+		rows,
+		totals: {
+			resources: rows.length,
+			apps: new Set(rows.map((r) => r.app)).size,
+			items: rows.reduce((sum, r) => sum + (r.measurement?.items ?? 0), 0),
+			bytes: rows.reduce((sum, r) => sum + (r.measurement?.bytes ?? 0), 0),
+		},
+		orphanedOverrides,
+	};
+}