cursedbelt-server 1.0.0

package/src/server/retention/target.ts

@@ -0,0 +1,613 @@
+/**
+ * The two shapes a governed resource can take — a sqlite table and a directory
+ * of files — behind one interface the sweeper drives.
+ *
+ * Everything policy-shaped (how old, how many, what the floor is) is decided in
+ * `policy.ts` and arrives here already resolved. A target's only job is to know
+ * how to count, preview and delete ITS medium. That split is what stops the next
+ * app from needing a fourth hand-rolled sweeper.
+ *
+ * ── `preview` is not a nicety ───────────────────────────────────────────────
+ * The station UI shows "this change would remove N items now" BEFORE the owner
+ * saves it. That number has to come from the same predicate the sweep runs, or
+ * it is a guess wearing a number's clothes — so `preview` and `sweep` share
+ * their WHERE clause by construction here, rather than by two functions that
+ * were correct on the day they were written.
+ */
+import type { Database } from "bun:sqlite";
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ArchiveSink } from "./archive";
+import { DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES } from "./archive";
+import type { EffectiveRetentionPolicy, RetentionDeclaration } from "./policy";
+import { categoryArchivesBeforeDelete, cutoffFor, retentionKey } from "./policy";
+import type { RetentionMeasurement, RetentionSweepReport } from "./store";
+
+export interface RetentionPreview {
+	/** Items the age rule would remove. */
+	aged: number;
+	/** Items the item-count backstop would remove on top of that. */
+	overflow: number;
+}
+
+export interface RetentionTarget {
+	readonly declaration: RetentionDeclaration;
+	measure(): RetentionMeasurement;
+	preview(policy: EffectiveRetentionPolicy, now: number): RetentionPreview;
+	sweep(policy: EffectiveRetentionPolicy, now: number): RetentionSweepReport;
+}
+
+/**
+ * Table and column names cannot be bound as parameters, so they are
+ * interpolated — and therefore must be proven safe rather than trusted. Every
+ * caller is first-party today; this is what keeps that true after someone wires
+ * a name in from a config file.
+ */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function ident(kind: string, name: string): string {
+	if (!IDENTIFIER.test(name))
+		throw new Error(`retention: unsafe ${kind} name ${JSON.stringify(name)}`);
+	return `"${name}"`;
+}
+
+/**
+ * 🔴 The structural half of the `archived-history` promise.
+ *
+ * The category says the rows are written somewhere safe before they go. These
+ * two targets DELETE — that is all they can do — so a declaration carrying an
+ * archiving category must not be constructible on one. Without this refusal the
+ * category would degrade, silently and at the worst possible moment, into
+ * "delete after a LONGER window than the standard allows", which is strictly
+ * worse than having no category at all.
+ *
+ * It throws at CONSTRUCTION, where the stack names the app and the resource,
+ * rather than at the first sweep hours later in a daemon nobody is watching.
+ */
+function refuseArchivingCategory(declaration: RetentionDeclaration, target: string): void {
+	if (!categoryArchivesBeforeDelete(declaration.category)) return;
+	throw new Error(
+		`retention: "${retentionKey(declaration.app, declaration.id)}" declares the ` +
+			`"${declaration.category}" category, which promises the rows are archived before they are ` +
+			`deleted — and ${target} only deletes. Use createArchivingSqliteTableTarget with an ` +
+			"ArchiveSink, or pick a category that honestly describes throwing the data away.",
+	);
+}
+
+export interface SqliteTableTargetOptions {
+	db: Database;
+	declaration: RetentionDeclaration;
+	table: string;
+	/** Column holding the row's age. Rows with NULL here are treated as ageless and kept. */
+	timeColumn: string;
+	/**
+	 * How `timeColumn` stores time. `epoch-ms` is the default; `iso` covers the
+	 * `2026-08-01T22:43:05.317Z` TEXT columns that are just as common across this
+	 * fleet (`orch`'s `job_runs`, and anything written by a scheduler that reasoned
+	 * in `Date().toISOString()`).
+	 *
+	 * ISO-8601 UTC strings sort lexicographically in the same order as the instants
+	 * they name, so the comparison stays a plain `<` against a bound parameter — no
+	 * per-row `strftime`, and the column's index is still usable.
+	 */
+	timeFormat?: "epoch-ms" | "iso";
+	/** Primary key used to address rows. Must be NOT NULL — `NOT IN` with a NULL yields NULL. */
+	idColumn?: string;
+	/**
+	 * A SQL predicate that, when TRUE, exempts a row from the AGE sweep — the
+	 * "still working state" rule. `apps/orch` uses it so a task parked for months
+	 * keeps the whole trail that explains why it parked; an age-only sweep would
+	 * delete exactly the rows the owner comes back to read.
+	 *
+	 * The item-count backstop deliberately IGNORES it: if the protected set alone
+	 * can overflow the table, the bound has to win or it is not a bound. When that
+	 * happens the sweeper says so loudly.
+	 */
+	protectWhere?: string;
+}
+
+export function createSqliteTableTarget(options: SqliteTableTargetOptions): RetentionTarget {
+	const { db, declaration } = options;
+	refuseArchivingCategory(declaration, "createSqliteTableTarget");
+	const table = ident("table", options.table);
+	const time = ident("column", options.timeColumn);
+	const id = ident("column", options.idColumn ?? "id");
+	const protect = options.protectWhere ? `(${options.protectWhere})` : null;
+
+	// The floor — "never delete the newest N, at any age" — is expressed once, as
+	// an exclusion of the newest N rows of the WHOLE table (not of the deletable
+	// subset): a floor that only counted deletable rows would let a table of
+	// entirely-protected rows plus one old row delete that row while claiming to
+	// keep three.
+	const newestN = `${id} NOT IN (SELECT ${id} FROM ${table} ORDER BY ${time} DESC LIMIT $floor)`;
+	const ageWhere =
+		`${time} IS NOT NULL AND ${time} < $cutoff` +
+		(protect ? ` AND NOT ${protect}` : "") +
+		` AND ${newestN}`;
+
+	// Statements are prepared LAZILY, and a missing table is a resource that does
+	// not exist YET rather than an error.
+	//
+	// This is not defensive padding: `orch` declares `plainjob_jobs` and
+	// `job_runs`, which its job library and scheduler create on first use — so at
+	// the moment the composition root builds its sweeper, neither table exists.
+	// Preparing eagerly threw `no such table` out of `createRetentionSweeper` and
+	// would have taken the whole daemon down at boot on a fresh machine, to bound
+	// a table with nothing in it. Any app whose schema is created by a dependency
+	// hits the same thing.
+	const tableExists = db.query(
+		"SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = $name",
+	);
+	const present = (): boolean => tableExists.get({ $name: options.table } as never) !== null;
+
+	const statements = new Map<string, ReturnType<Database["query"]>>();
+	const prepared = (sql: string): ReturnType<Database["query"]> => {
+		let statement = statements.get(sql);
+		if (!statement) {
+			statement = db.query(sql);
+			statements.set(sql, statement);
+		}
+		return statement;
+	};
+
+	const countAll = () => prepared(`SELECT COUNT(*) AS n FROM ${table}`);
+	const oldest = () => prepared(`SELECT MIN(${time}) AS t FROM ${table}`);
+	const countAged = () => prepared(`SELECT COUNT(*) AS n FROM ${table} WHERE ${ageWhere}`);
+	const deleteAged = () =>
+		prepared(`DELETE FROM ${table} WHERE ${id} IN (SELECT ${id} FROM ${table} WHERE ${ageWhere})`);
+	const deleteOldest = () =>
+		prepared(
+			`DELETE FROM ${table} WHERE ${id} IN (SELECT ${id} FROM ${table} ORDER BY ${time} ASC LIMIT $excess)`,
+		);
+
+	const count = (): number => (countAll().get() as { n: number }).n;
+
+	const isIso = options.timeFormat === "iso";
+	/** The cutoff in the column's own units, so the comparison stays a plain `<`. */
+	const asColumnTime = (ms: number): number | string => (isIso ? new Date(ms).toISOString() : ms);
+	/** …and back, for the UI's "oldest item" readout. */
+	const asMs = (value: unknown): number | undefined => {
+		if (typeof value === "number") return value;
+		if (typeof value === "string") {
+			const parsed = Date.parse(value);
+			return Number.isNaN(parsed) ? undefined : parsed;
+		}
+		return undefined;
+	};
+
+	/** How many the backstop removes once the age rule has run. */
+	function overflowExcess(policy: EffectiveRetentionPolicy, remaining: number): number {
+		if (!policy.enabled || policy.maxItems <= 0) return 0;
+		const overCap = remaining - policy.maxItems;
+		// Never below the floor, even to honor the cap: the floor is the one rule
+		// with no exceptions.
+		const abovefloor = remaining - policy.floorItems;
+		return Math.max(0, Math.min(overCap, abovefloor));
+	}
+
+	return {
+		declaration,
+		measure() {
+			if (!present()) return { items: 0 };
+			const oldestAt = asMs((oldest().get() as { t: unknown }).t);
+			return { items: count(), ...(oldestAt === undefined ? {} : { oldestAt }) };
+		},
+		preview(policy, now) {
+			if (!policy.enabled || !present()) return { aged: 0, overflow: 0 };
+			const cutoff = cutoffFor(policy, now);
+			const aged =
+				cutoff === null
+					? 0
+					: (
+							countAged().get({
+								$cutoff: asColumnTime(cutoff),
+								$floor: policy.floorItems,
+							} as never) as { n: number }
+						).n;
+			return { aged, overflow: overflowExcess(policy, count() - aged) };
+		},
+		sweep(policy, now) {
+			if (!policy.enabled || !present()) return { at: now, aged: 0, overflow: 0 };
+			let aged = 0;
+			const cutoff = cutoffFor(policy, now);
+			if (cutoff !== null) {
+				aged = deleteAged().run({
+					$cutoff: asColumnTime(cutoff),
+					$floor: policy.floorItems,
+				} as never).changes;
+			}
+			const excess = overflowExcess(policy, count());
+			const overflow = excess > 0 ? deleteOldest().run({ $excess: excess } as never).changes : 0;
+			return { at: now, aged, overflow };
+		},
+	};
+}
+
+export interface FileDirTargetOptions {
+	declaration: RetentionDeclaration;
+	dir: string;
+	/** Only files matching this are governed. Anything else in the dir is invisible. */
+	match?: RegExp;
+	/** Injectable for tests; defaults to the file's mtime. */
+	timeOf?: (path: string, stat: { mtimeMs: number }) => number;
+	/**
+	 * Files this sweep must never delete, whatever the policy says — the
+	 * filesystem counterpart of `protectWhere`.
+	 *
+	 * Called once per sweep and given every governed file, so the caller can
+	 * resolve the protected set with ONE query rather than one per file (`orch`
+	 * asks its database for the attempts that are still live or whose task has not
+	 * settled). Unlike `protectWhere`, this holds against the byte and item caps
+	 * TOO: a bound that deletes a running worker's live transcript to save disk has
+	 * traded a disk problem for a debugging one, and unlinking a file that is still
+	 * being appended to loses the writer's output with no error anywhere.
+	 */
+	protect?: (
+		files: ReadonlyArray<{ name: string; path: string; at: number; bytes: number }>,
+	) => Set<string>;
+}
+
+interface FileEntry {
+	name: string;
+	path: string;
+	at: number;
+	bytes: number;
+}
+
+/**
+ * A directory of files — attempt transcripts, generated art, exports.
+ *
+ * Only files DIRECTLY in `dir` and matching `match` are ever considered: a tool
+ * that deletes things gets to delete only what it can prove it owns, which is
+ * the rule `deploy-engine/backupRetention.ts` arrived at after the same
+ * question. Subdirectories are left entirely alone.
+ */
+export function createFileDirTarget(options: FileDirTargetOptions): RetentionTarget {
+	const { declaration, dir } = options;
+	refuseArchivingCategory(declaration, "createFileDirTarget");
+	const match = options.match;
+	const timeOf = options.timeOf ?? ((_p, stat) => stat.mtimeMs);
+
+	function list(): FileEntry[] {
+		let names: string[];
+		try {
+			names = readdirSync(dir);
+		} catch {
+			return []; // not created yet — a resource with nothing in it
+		}
+		const entries: FileEntry[] = [];
+		for (const name of names) {
+			if (match && !match.test(name)) continue;
+			const path = join(dir, name);
+			try {
+				const stat = statSync(path);
+				if (!stat.isFile()) continue;
+				entries.push({ name, path, at: timeOf(path, stat), bytes: stat.size });
+			} catch {
+				// vanished between readdir and stat — nothing to govern
+			}
+		}
+		return entries.sort((a, b) => b.at - a.at); // newest first
+	}
+
+	/** The plan, shared by preview and sweep so they cannot disagree. */
+	function plan(
+		policy: EffectiveRetentionPolicy,
+		now: number,
+	): { aged: FileEntry[]; overflow: FileEntry[]; protectedCount: number } {
+		const entries = list();
+		if (!policy.enabled) return { aged: [], overflow: [], protectedCount: 0 };
+
+		// Protected by the caller (live writer / unsettled task), then by the floor.
+		// Both are absolute: neither the age rule nor either cap may touch them.
+		const kept = new Set(options.protect ? options.protect(entries) : []);
+		for (const entry of entries.slice(0, policy.floorItems)) kept.add(entry.path);
+		const deletable = entries.filter((e) => !kept.has(e.path));
+
+		const cutoff = cutoffFor(policy, now);
+		const aged = cutoff === null ? [] : deletable.filter((e) => e.at < cutoff);
+		const agedPaths = new Set(aged.map((e) => e.path));
+
+		// Oldest first: the cap always gives up the least recently useful thing.
+		const candidates = deletable.filter((e) => !agedPaths.has(e.path)).sort((a, b) => a.at - b.at);
+		const overflow: FileEntry[] = [];
+
+		if (policy.maxItems > 0) {
+			let remaining = entries.length - aged.length;
+			for (const entry of candidates) {
+				if (remaining <= policy.maxItems) break;
+				overflow.push(entry);
+				remaining--;
+			}
+		}
+		if (policy.maxBytes > 0) {
+			const chosen = new Set(overflow.map((e) => e.path));
+			let bytes = entries.reduce(
+				(sum, e) => (agedPaths.has(e.path) || chosen.has(e.path) ? sum : sum + e.bytes),
+				0,
+			);
+			for (const entry of candidates) {
+				if (bytes <= policy.maxBytes) break;
+				if (chosen.has(entry.path)) continue;
+				overflow.push(entry);
+				chosen.add(entry.path);
+				bytes -= entry.bytes;
+			}
+		}
+		return { aged, overflow, protectedCount: entries.length - deletable.length };
+	}
+
+	return {
+		declaration,
+		measure() {
+			const entries = list();
+			const result: RetentionMeasurement = {
+				items: entries.length,
+				bytes: entries.reduce((sum, e) => sum + e.bytes, 0),
+			};
+			const last = entries[entries.length - 1];
+			if (last) result.oldestAt = last.at;
+			return result;
+		},
+		preview(policy, now) {
+			const { aged, overflow } = plan(policy, now);
+			return { aged: aged.length, overflow: overflow.length };
+		},
+		sweep(policy, now) {
+			const { aged, overflow, protectedCount } = plan(policy, now);
+			let bytesFreed = 0;
+			let agedRemoved = 0;
+			let overflowRemoved = 0;
+			for (const [entries, isAged] of [
+				[aged, true],
+				[overflow, false],
+			] as const) {
+				for (const entry of entries) {
+					try {
+						rmSync(entry.path, { force: true });
+						bytesFreed += entry.bytes;
+						if (isAged) agedRemoved++;
+						else overflowRemoved++;
+					} catch {
+						// A file that will not delete is a housekeeping problem, never a
+						// reason to abandon the rest of the sweep.
+					}
+				}
+			}
+			return {
+				at: now,
+				aged: agedRemoved,
+				overflow: overflowRemoved,
+				bytesFreed,
+				protectedItems: protectedCount,
+			};
+		},
+	};
+}
+
+// ── archive-then-trim ────────────────────────────────────────────────────────
+
+export interface ArchivingSqliteTableTargetOptions
+	extends Omit<SqliteTableTargetOptions, "declaration"> {
+	declaration: RetentionDeclaration;
+	/** Where the rows go before they leave the table. */
+	archive: ArchiveSink;
+	/**
+	 * Columns written to the archive, in order. Defaults to every column the
+	 * table has at construction — which is what an append-only history wants: the
+	 * archive is the row, not a projection somebody chose on a Tuesday.
+	 */
+	columns?: string[];
+	/**
+	 * Most rows one sweep will move. The sweep is synchronous and the rows are
+	 * held in memory to be serialized, so a first run against years of history
+	 * must not try to do it in one bite. Successive sweeps drain the rest.
+	 */
+	maxBatch?: number;
+	/**
+	 * How many bytes of uncollected archive a STAGED home may hold before this
+	 * target refuses to trim. See `archive.ts` — this is the "refuse if the last
+	 * successful pull is stale" rule, expressed in the one fact a deployed box can
+	 * observe for itself.
+	 */
+	pendingBudgetBytes?: number;
+}
+
+/**
+ * A sqlite table whose aged rows are ARCHIVED and then deleted — the runtime for
+ * the `archived-history` category.
+ *
+ * Everything about WHICH rows is shared with `createSqliteTableTarget`: the same
+ * age predicate, the same `protectWhere` liveness exemption, the same floor, the
+ * same cap. What differs is the one step in the middle, and it is the whole
+ * point: nothing is deleted until `archive.write()` has proven the bytes are on
+ * disk, and `write()` throws rather than reporting failure so there is no path
+ * where "the archive did not happen" reaches a DELETE.
+ *
+ * 🔴 The item-count backstop archives too. A cap that dumped the oldest rows
+ * straight to /dev/null the moment a table overflowed would mean the ONE case
+ * where the history is growing fastest is the one case it is destroyed — an
+ * archiving resource that has an unarchived escape hatch is not an archiving
+ * resource.
+ */
+export function createArchivingSqliteTableTarget(
+	options: ArchivingSqliteTableTargetOptions,
+): RetentionTarget {
+	const { db, declaration, archive } = options;
+	if (!categoryArchivesBeforeDelete(declaration.category)) {
+		throw new Error(
+			`retention: "${retentionKey(declaration.app, declaration.id)}" uses ` +
+				"createArchivingSqliteTableTarget but its category does not archive before deleting " +
+				`(${declaration.category}). Use createSqliteTableTarget, or declare "archived-history".`,
+		);
+	}
+	const key = retentionKey(declaration.app, declaration.id);
+	const table = ident("table", options.table);
+	const time = ident("column", options.timeColumn);
+	const idColumn = options.idColumn ?? "id";
+	const id = ident("column", idColumn);
+	const protect = options.protectWhere ? `(${options.protectWhere})` : null;
+	const maxBatch = options.maxBatch ?? 50_000;
+	const pendingBudget = options.pendingBudgetBytes ?? DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES;
+
+	// Identical to the plain target's, deliberately: the predicate that decides
+	// what ages out must not fork, or the preview the owner reads and the sweep
+	// that runs stop being the same question.
+	const newestN = `${id} NOT IN (SELECT ${id} FROM ${table} ORDER BY ${time} DESC LIMIT $floor)`;
+	const ageWhere =
+		`${time} IS NOT NULL AND ${time} < $cutoff` +
+		(protect ? ` AND NOT ${protect}` : "") +
+		` AND ${newestN}`;
+
+	const tableExists = db.query(
+		"SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = $name",
+	);
+	const present = (): boolean => tableExists.get({ $name: options.table } as never) !== null;
+
+	const statements = new Map<string, ReturnType<Database["query"]>>();
+	const prepared = (sql: string): ReturnType<Database["query"]> => {
+		let statement = statements.get(sql);
+		if (!statement) {
+			statement = db.query(sql);
+			statements.set(sql, statement);
+		}
+		return statement;
+	};
+
+	/** Resolved lazily for the same reason statements are: the table may not exist yet. */
+	let columnList: string | null = null;
+	const columns = (): string => {
+		if (columnList) return columnList;
+		if (options.columns?.length) {
+			columnList = options.columns.map((c) => ident("column", c)).join(", ");
+			return columnList;
+		}
+		const info = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+		columnList = info.map((row) => ident("column", row.name)).join(", ") || "*";
+		return columnList;
+	};
+
+	const count = (): number =>
+		(prepared(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
+
+	const isIso = options.timeFormat === "iso";
+	const asColumnTime = (ms: number): number | string => (isIso ? new Date(ms).toISOString() : ms);
+	const asMs = (value: unknown): number | undefined => {
+		if (typeof value === "number") return value;
+		if (typeof value === "string") {
+			const parsed = Date.parse(value);
+			return Number.isNaN(parsed) ? undefined : parsed;
+		}
+		return undefined;
+	};
+
+	function overflowExcess(policy: EffectiveRetentionPolicy, remaining: number): number {
+		if (!policy.enabled || policy.maxItems <= 0) return 0;
+		return Math.max(0, Math.min(remaining - policy.maxItems, remaining - policy.floorItems));
+	}
+
+	const agedRows = (cutoff: number, floor: number, limit: number): Array<Record<string, unknown>> =>
+		prepared(
+			`SELECT ${columns()} FROM ${table} WHERE ${ageWhere} ORDER BY ${time} ASC LIMIT $limit`,
+		).all({ $cutoff: asColumnTime(cutoff), $floor: floor, $limit: limit } as never) as Array<
+			Record<string, unknown>
+		>;
+
+	const oldestRows = (excess: number): Array<Record<string, unknown>> =>
+		prepared(
+			`SELECT ${columns()} FROM ${table} ORDER BY ${time} ASC LIMIT $excess`,
+		).all({ $excess: excess } as never) as Array<Record<string, unknown>>;
+
+	/**
+	 * Archive the rows, THEN delete exactly those ids. Never a WHERE re-run: the
+	 * rows that were archived and the rows that are deleted have to be the same
+	 * set, and a predicate evaluated twice against a live table is two sets.
+	 */
+	function archiveThenDelete(rows: Array<Record<string, unknown>>, at: number): number {
+		const ids = rows.map((row) => row[idColumn]);
+		if (ids.some((value) => value === null || value === undefined)) {
+			throw new Error(
+				`retention: ${key} cannot archive rows whose "${idColumn}" is NULL — a row this sweep ` +
+					"could not address afterwards must not be archived, or the archive would grow a copy " +
+					"of a row that stays in the table for ever.",
+			);
+		}
+		const segment = archive.write(rows, at);
+		const placeholders = ids.map(() => "?").join(", ");
+		db.query(`DELETE FROM ${table} WHERE ${id} IN (${placeholders})`).run(...(ids as never[]));
+		return segment.bytes;
+	}
+
+	return {
+		declaration,
+		measure() {
+			if (!present()) return { items: 0 };
+			const oldestAt = asMs(
+				(prepared(`SELECT MIN(${time}) AS t FROM ${table}`).get() as { t: unknown }).t,
+			);
+			return { items: count(), ...(oldestAt === undefined ? {} : { oldestAt }) };
+		},
+		preview(policy, now) {
+			if (!policy.enabled || !present()) return { aged: 0, overflow: 0 };
+			const cutoff = cutoffFor(policy, now);
+			const aged =
+				cutoff === null
+					? 0
+					: (
+							prepared(`SELECT COUNT(*) AS n FROM ${table} WHERE ${ageWhere}`).get({
+								$cutoff: asColumnTime(cutoff),
+								$floor: policy.floorItems,
+							} as never) as { n: number }
+						).n;
+			return { aged: Math.min(aged, maxBatch), overflow: overflowExcess(policy, count() - aged) };
+		},
+		sweep(policy, now) {
+			if (!policy.enabled || !present()) return { at: now, aged: 0, overflow: 0 };
+
+			// 🔴 The staleness refusal, before a single row is read. A staged archive
+			// that nobody is collecting means the box would be trading a bounded table
+			// for an unbounded archive on the same disk — and, worse, doing it while
+			// the ONLY copy of the trimmed history sits on the box the trim was
+			// supposed to protect. Stop, and say why.
+			const pending = archive.pendingBytes();
+			if (!archive.terminal && pending > pendingBudget) {
+				return {
+					at: now,
+					aged: 0,
+					overflow: 0,
+					blocked:
+						`${Math.round(pending / 1048576)} MB of archived history in ${archive.dir} has not been ` +
+						`collected (budget ${Math.round(pendingBudget / 1048576)} MB). Nothing was trimmed: the ` +
+						"archive is this history's only other copy, so a stale collector must stop the trim, " +
+						"not be outrun by it. Run the Mac's `bun run backups:pull-prod`.",
+				};
+			}
+
+			let aged = 0;
+			let archivedBytes = 0;
+			const cutoff = cutoffFor(policy, now);
+			if (cutoff !== null) {
+				const rows = agedRows(cutoff, policy.floorItems, maxBatch);
+				if (rows.length > 0) {
+					archivedBytes += archiveThenDelete(rows, now);
+					aged = rows.length;
+				}
+			}
+			let overflow = 0;
+			const excess = Math.min(overflowExcess(policy, count()), maxBatch);
+			if (excess > 0) {
+				const rows = oldestRows(excess);
+				if (rows.length > 0) {
+					archivedBytes += archiveThenDelete(rows, now + 1);
+					overflow = rows.length;
+				}
+			}
+			const moved = aged + overflow;
+			return {
+				at: now,
+				aged,
+				overflow,
+				...(moved > 0 ? { archived: moved, archivedBytes } : {}),
+			};
+		},
+	};
+}

package/src/server/search/index.ts

@@ -0,0 +1,12 @@
+// The saas search tier (04 §3) — the far side of `SearchProvider` for a pooled
+// Postgres. `createSaasHostServices` is the near side a deployment actually
+// calls; these are exported for a host that wires the tier by hand and for the
+// migration step that creates the schema.
+export { createPgSearchProvider, type PgSearchProviderOptions } from './pgSearchProvider';
+export {
+  ensureSaasSearchSchema,
+  PG_RANK_WEIGHTS,
+  PG_SEARCH_CHUNKS_DDL,
+  PG_SEARCH_DDL,
+  PG_SEARCH_DOCS_DDL,
+} from './pgSearchSchema';