cursedbelt-server 1.0.0

package/src/server/retention/index.ts

@@ -0,0 +1,101 @@
+/**
+ * `cursedbelt-server/retention` — THE fleet's one retention standard.
+ *
+ * ── Why this lives in cursedbelt ────────────────────────────────────────────
+ * Retention used to be spoken in three unrelated vocabularies: this
+ * category-based opt-in design (born in `cursed-satellites/satellite-kit`), the
+ * DB-backed audit|meter WINDOWS in `cursedbelt-cc/drivers`' retentionPolicy
+ * (billing evidence — a genuinely different concern that keeps the name
+ * {@link RetentionWindows}), and `deploy-engine/backupRetention`'s artifact
+ * pruning. DEDUP-8(c) made THIS one canonical and moved it here, so a single
+ * copy serves cursed-core, cursed-satellites and every generated app, and
+ * `RetentionPolicy` names exactly one thing across the fleet. `satellite-kit`'s
+ * `./retention` subpath is now a thin re-export of this module.
+ *
+ * An app declares what it owns and starts a sweeper; the station reads and
+ * edits the policies. Nothing else in the fleet should contain a timer that
+ * deletes old rows.
+ *
+ *   const sweeper = createRetentionSweeper({
+ *     app: "orch",
+ *     targets: [
+ *       createSqliteTableTarget({ db, declaration: {...}, table: "events", timeColumn: "at" }),
+ *       createFileDirTarget({ declaration: {...}, dir: attemptLogs.dir, match: /\.jsonl$/ }),
+ *     ],
+ *   });
+ *   sweeper.start();
+ *
+ * See `policy.ts` for the rule that decides whether a resource may be governed
+ * at all — retention is opt-in by category, and no category can describe data
+ * the owner would miss (which is exactly why billing evidence is NOT a category
+ * and lives in `retentionPolicy.ts` instead).
+ */
+export {
+	archiveStamp,
+	createJsonlArchive,
+	DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES,
+	resolveArchiveHome,
+	verifyArchive,
+	type ArchiveHome,
+	type ArchiveSegment,
+	type ArchiveSink,
+	type JsonlArchiveOptions,
+} from "./archive";
+export {
+	ARCHIVING_RETENTION_CATEGORIES,
+	assertRetentionDeclaration,
+	categoryArchivesBeforeDelete,
+	cutoffFor,
+	DAY_MS,
+	FLEET_DEFAULT_RETENTION_DAYS,
+	RETENTION_CATEGORIES,
+	RETENTION_CATEGORY_KEYS,
+	RETENTION_MAX_DAYS,
+	RETENTION_MIN_DAYS,
+	resolveRetentionPolicy,
+	retentionKey,
+	type EffectiveRetentionPolicy,
+	// The fleet's one `RetentionPolicy`: the resolved, in-effect policy a sweep
+	// runs with. An alias, so callers can spell the canonical name and the two
+	// specialized concepts (billing `RetentionWindows`, backup
+	// `BackupRetentionPolicy`) no longer collide on it.
+	type RetentionPolicy,
+	type RetentionCategory,
+	type RetentionDeclaration,
+	type RetentionFieldSource,
+	type RetentionOverride,
+	type RetentionUnit,
+} from "./policy";
+export {
+	publishRetention,
+	readRetentionOverrides,
+	readRetentionRegistry,
+	resolveRetentionHome,
+	setRetentionHomeForTests,
+	writeRetentionOverride,
+	type PublishedResource,
+	type RetentionMeasurement,
+	type RetentionOverridesFile,
+	type RetentionPublication,
+	type RetentionSweepReport,
+} from "./store";
+export {
+	createArchivingSqliteTableTarget,
+	createFileDirTarget,
+	createSqliteTableTarget,
+	type ArchivingSqliteTableTargetOptions,
+	type FileDirTargetOptions,
+	type RetentionPreview,
+	type RetentionTarget,
+	type SqliteTableTargetOptions,
+} from "./target";
+export {
+	createRetentionSweeper,
+	DEFAULT_SWEEP_INTERVAL_MS,
+	OVERRIDES_PULSE_MS,
+	type CreateRetentionSweeperOptions,
+	type ResourceOutcome,
+	type RetentionRunReport,
+	type RetentionSweeper,
+} from "./sweeper";
+export { buildRetentionFleetView, type RetentionFleetRow, type RetentionFleetView } from "./fleet";

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

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test";
+import {
+	ARCHIVING_RETENTION_CATEGORIES,
+	assertRetentionDeclaration,
+	categoryArchivesBeforeDelete,
+	cutoffFor,
+	DAY_MS,
+	FLEET_DEFAULT_RETENTION_DAYS,
+	RETENTION_CATEGORIES,
+	RETENTION_CATEGORY_KEYS,
+	resolveRetentionPolicy,
+	retentionKey,
+	type RetentionDeclaration,
+} from "./policy";
+
+const decl = (over: Partial<RetentionDeclaration> = {}): RetentionDeclaration => ({
+	app: "orch",
+	id: "events",
+	label: "Event trail",
+	category: "event-log",
+	unit: "rows",
+	location: "orch.sqlite · events",
+	consequence: "the narrative of past runs",
+	...over,
+});
+
+describe("the category vocabulary is the guard on long-term data", () => {
+	test("no DELETING category defaults longer than the owner's two-week standard", () => {
+		// The standard is the whole point: a category wanting longer would be
+		// describing data that belongs to the user, which this vocabulary must not
+		// be able to express. The one exemption is a category that ARCHIVES first —
+		// its number says where the history lives, not how long it exists — and it
+		// is tested separately below so the exemption cannot widen quietly.
+		for (const key of RETENTION_CATEGORY_KEYS) {
+			expect(RETENTION_CATEGORIES[key].defaultDays).toBeGreaterThan(0);
+			if (categoryArchivesBeforeDelete(key)) continue;
+			expect(RETENTION_CATEGORIES[key].defaultDays, `${key} deletes, so it is capped`).toBeLessThanOrEqual(
+				FLEET_DEFAULT_RETENTION_DAYS,
+			);
+		}
+	});
+
+	test("the longer-than-the-standard exemption belongs to archiving categories ONLY", () => {
+		// Read this the other way round: any category that is over the standard has
+		// to be one that archives. A future entry that reaches for 90 days without
+		// an archive behind it fails here rather than at a prod DELETE.
+		const overTheStandard = RETENTION_CATEGORY_KEYS.filter(
+			(key) => RETENTION_CATEGORIES[key].defaultDays > FLEET_DEFAULT_RETENTION_DAYS,
+		);
+		expect(overTheStandard.sort()).toEqual([...ARCHIVING_RETENTION_CATEGORIES].sort());
+		// And the exemption exists at all — a green test over an empty set would
+		// keep passing if `archived-history` were deleted tomorrow.
+		expect(ARCHIVING_RETENTION_CATEGORIES).toContain("archived-history");
+		expect(categoryArchivesBeforeDelete("archived-history")).toBe(true);
+		expect(categoryArchivesBeforeDelete("event-log")).toBe(false);
+	});
+
+	test("every category explains itself — the UI shows the summary, not the key", () => {
+		for (const key of RETENTION_CATEGORY_KEYS) {
+			expect(RETENTION_CATEGORIES[key].summary.length).toBeGreaterThan(20);
+			expect(RETENTION_CATEGORIES[key].label.length).toBeGreaterThan(2);
+		}
+	});
+
+	test("an unknown category is refused, and the message names the closed set", () => {
+		expect(() => assertRetentionDeclaration(decl({ category: "user-notes" as never }))).toThrow(
+			/unknown category/,
+		);
+		expect(() => assertRetentionDeclaration(decl({ category: "user-notes" as never }))).toThrow(
+			/opt-in/,
+		);
+	});
+
+	test("a declaration must say what is lost — the sentence the owner reads before changing it", () => {
+		expect(() => assertRetentionDeclaration(decl({ consequence: "  " }))).toThrow(/what is lost/);
+	});
+
+	test("ids and app keys must be usable as an override key", () => {
+		expect(() => assertRetentionDeclaration(decl({ id: "Events" }))).toThrow(/lower-kebab/);
+		expect(() => assertRetentionDeclaration(decl({ app: "orch/../etc" }))).toThrow(/lower-kebab/);
+		expect(retentionKey("orch", "events")).toBe("orch:events");
+	});
+});
+
+describe("resolveRetentionPolicy", () => {
+	test("with no override it is the category default, sourced as such", () => {
+		const policy = resolveRetentionPolicy(decl());
+		expect(policy.days).toBe(RETENTION_CATEGORIES["event-log"].defaultDays);
+		expect(policy.sources.days).toBe("default");
+		expect(policy.enabled).toBe(true);
+	});
+
+	test("a declaration may set a shorter default than its category", () => {
+		expect(resolveRetentionPolicy(decl({ defaultDays: 3 })).days).toBe(3);
+	});
+
+	test("an override wins and is sourced as an override", () => {
+		const policy = resolveRetentionPolicy(decl(), { days: 30 });
+		expect(policy.days).toBe(30);
+		expect(policy.sources.days).toBe("override");
+	});
+
+	test("an out-of-bounds override is clamped and REPORTS that it was", () => {
+		// Silently clamping would show the owner a number the sweep does not use.
+		const policy = resolveRetentionPolicy(decl({ maxDays: 90 }), { days: 4000 });
+		expect(policy.days).toBe(90);
+		expect(policy.clamped).toEqual({ field: "days", requested: 4000, applied: 90 });
+	});
+
+	test("days: 0 means keep forever and is NOT clamped up to minDays", () => {
+		// Clamping it would silently re-arm a sweep the owner deliberately turned off.
+		const policy = resolveRetentionPolicy(decl({ minDays: 7 }), { days: 0 });
+		expect(policy.days).toBe(0);
+		expect(policy.clamped).toBeUndefined();
+		expect(cutoffFor(policy, 1_000_000)).toBeNull();
+	});
+
+	test("enabled: false suspends the age rule entirely", () => {
+		const policy = resolveRetentionPolicy(decl(), { enabled: false });
+		expect(policy.enabled).toBe(false);
+		expect(cutoffFor(policy, 1_000_000)).toBeNull();
+	});
+
+	test("the floor survives into the effective policy", () => {
+		expect(resolveRetentionPolicy(decl({ floorItems: 25 })).floorItems).toBe(25);
+	});
+
+	test("cutoff is the age rule in one place", () => {
+		const now = 10 * DAY_MS;
+		expect(cutoffFor(resolveRetentionPolicy(decl(), { days: 3 }), now)).toBe(now - 3 * DAY_MS);
+	});
+});

package/src/server/retention/policy.ts

@@ -0,0 +1,392 @@
+/**
+ * The fleet's retention VOCABULARY — one place that decides how long
+ * regenerable, diagnostic data lives, and what may never be governed this way.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * Before this module, every app that bounded a growing table did it by hand and
+ * decided the number privately: `watchdog_runs` keeps the newest N on insert,
+ * `ai_check_runs` keeps N per check, the proposal ledger caps at 200,
+ * orch's own `eventRetention` was a whole bespoke sweeper with its own timer, and `deploy-engine/backupRetention.ts` a second one with different
+ * rules. Meanwhile the things nobody had written a rule for grew without limit:
+ * orch's own state directory reached **1.0 GB** — 74 MB of attempt transcripts and a
+ * single 70 MB peer-link `dedupe.json` holding 118 entries — with no policy, no
+ * backup, and nothing that could report it.
+ *
+ * The owner's ask (2026-08-01) was for ONE standard: a default that keeps
+ * diagnostic data no more than two weeks, per-resource overrides, a UI to see
+ * and change them, and no per-app copies of the logic.
+ *
+ * ── The rule that makes this safe: retention is OPT-IN, by CATEGORY ─────────
+ * A resource can only be swept if it declares a `RetentionCategory`, and the
+ * categories below describe exactly one kind of data: **a record that exists so
+ * a human can find out what happened, and whose loss costs nothing but
+ * hindsight.** There is deliberately no category that could describe a note, a
+ * saved setting, a password, a save state, a shelf row or a vault entry — so
+ * "should this table have a policy?" is answered by whether an honest category
+ * exists for it, not by an agent's judgment in the moment.
+ *
+ * Long-term data is therefore protected by ABSENCE, not by a denylist a future
+ * table would have to be remembered into. Two further gates back it up:
+ * `scripts/retentionPolicies.test.ts` pins the exact (app, resource) set that
+ * sweeps anywhere in this repo — adding one is an edit to a reviewed list, never
+ * a side effect — and `floorItems` below means even a mis-set policy cannot
+ * empty a resource.
+ *
+ * ── The missing middle, added 2026-08-25: ARCHIVE-then-trim ─────────────────
+ * Until now a resource was either governed (swept, gone forever) or undeclared
+ * (kept forever on a 6.7 GB prod root). Neither describes an append-only history
+ * whose recent window is load-bearing and whose tail is worth keeping but not
+ * worth keeping THERE. `archived-history` is that third answer: the instance
+ * keeps a bounded window and everything older is written to a verified,
+ * append-only archive BEFORE a single row is deleted.
+ *
+ * That is why it is the one category allowed a default longer than the owner's
+ * two-week standard, and the exemption is narrow by construction rather than by
+ * convention: `archivesBeforeDelete` is a property of the CATEGORY, the
+ * plain-delete targets in `target.ts` REFUSE a declaration that carries it, and
+ * the archiving target refuses to delete a row it cannot prove it has archived.
+ * A category that could be swept by a target that only deletes would be a
+ * longer retention with no archive at the end of it — strictly worse than having
+ * no category at all.
+ *
+ * ── Anything that grows without bound and is NOT sweepable is a design bug ──
+ * The other half of the standard. If a resource grows forever and no category
+ * fits it, the answer is not a longer retention — it is that the thing should
+ * not be accumulating (peer-link's dedupe file was storing 600 KB command
+ * RESULTS to answer a replay question that needs only an id).
+ */
+
+/**
+ * The closed set of things a retention policy may govern.
+ *
+ * Each entry's `defaultDays` is the fleet default for that shape. The owner's
+ * standard is two weeks; a DELETING category is shorter only where the data is
+ * cheaper than that to lose, and none is longer — a deleting category that
+ * wanted a longer default would be describing data that belongs to the user,
+ * which is the exact case this vocabulary refuses to express.
+ *
+ * `archivesBeforeDelete` is the single, narrow exemption: the rows leave the
+ * instance but not existence, so the number is a WINDOW rather than a lifetime
+ * and may honestly be longer. `policy.spec.ts` pins both halves of that rule.
+ */
+export const RETENTION_CATEGORIES = {
+	"audit-log": {
+		label: "Audit log",
+		defaultDays: 14,
+		summary: "Who did what, kept so an incident can be reconstructed. Read only after a problem.",
+	},
+	"event-log": {
+		label: "Event log",
+		defaultDays: 14,
+		summary: "State transitions and activity trails. The narrative of a run, not the run's result.",
+	},
+	"run-log": {
+		label: "Run log",
+		defaultDays: 14,
+		summary: "One row per execution of a job, check or sweep — its outcome ledger.",
+	},
+	transcript: {
+		label: "Transcript",
+		defaultDays: 14,
+		summary: "Verbatim worker/tool output. Large, read once during triage, never again.",
+	},
+	metric: {
+		label: "Metric",
+		defaultDays: 14,
+		summary: "Sampled counters and telemetry. Interesting in aggregate and recent, not per-row.",
+	},
+	cache: {
+		label: "Cache",
+		defaultDays: 7,
+		summary: "Recomputable from its source. Shorter by default because losing it costs a refetch.",
+	},
+	"replica-mirror": {
+		label: "Replica mirror",
+		defaultDays: 7,
+		summary: "A copy of state that another instance owns authoritatively. Never the only copy.",
+	},
+	"queue-result": {
+		label: "Queue result",
+		defaultDays: 3,
+		summary:
+			"Completed command/job rows and their payloads, kept only long enough to answer a retry or a replay.",
+	},
+	"scratch-artifact": {
+		label: "Scratch artifact",
+		defaultDays: 14,
+		summary:
+			"Generated files kept for inspection — renders, dumps, exports. Reproducible by rerunning.",
+	},
+	"archived-history": {
+		label: "Archived history",
+		defaultDays: 30,
+		archivesBeforeDelete: true,
+		summary:
+			"Append-only history whose recent window is load-bearing and whose tail is not. The instance keeps the window; everything older is written to a verified archive first and only then deleted, so the number is where the history LIVES, never how long it exists.",
+	},
+} as const satisfies Record<
+	string,
+	{ label: string; defaultDays: number; summary: string; archivesBeforeDelete?: boolean }
+>;
+
+export type RetentionCategory = keyof typeof RETENTION_CATEGORIES;
+
+export const RETENTION_CATEGORY_KEYS = Object.keys(RETENTION_CATEGORIES) as RetentionCategory[];
+
+/**
+ * Does this category promise the rows survive the sweep somewhere else?
+ *
+ * The one question that decides which TARGET may govern a resource, so it is
+ * asked as a function rather than by reading a property at four call sites — a
+ * plain-delete target checks it to refuse, the archiving target checks it to
+ * insist, and `policy.spec.ts` checks it to allow the longer default.
+ */
+export function categoryArchivesBeforeDelete(category: RetentionCategory): boolean {
+	// An UNKNOWN category answers `false` rather than throwing. It is asked at
+	// target construction, which runs before `assertRetentionDeclaration` gets to
+	// say "unknown category (the closed set is …)" — and a TypeError about an
+	// undefined property would replace that message with one that names nothing.
+	const entry = RETENTION_CATEGORIES[category] as { archivesBeforeDelete?: boolean } | undefined;
+	return entry?.archivesBeforeDelete === true;
+}
+
+/** The categories whose rows are archived rather than destroyed. */
+export const ARCHIVING_RETENTION_CATEGORIES = RETENTION_CATEGORY_KEYS.filter(
+	categoryArchivesBeforeDelete,
+);
+
+/**
+ * The owner's standard (2026-08-01): diagnostic data lives two weeks unless
+ * something says otherwise. Exported because the UI states it as the house rule
+ * rather than repeating a literal, and because a category's default is only ever
+ * allowed to be this or shorter (pinned by `policy.test.ts`).
+ */
+export const FLEET_DEFAULT_RETENTION_DAYS = 14;
+
+/** Bounds an override is clamped into unless a declaration narrows them. */
+export const RETENTION_MIN_DAYS = 1;
+export const RETENTION_MAX_DAYS = 365;
+
+/** What a resource is counted in — decides the UI's noun and the target's `measure`. */
+export type RetentionUnit = "rows" | "files";
+
+/**
+ * One governable resource, declared by the app that owns it.
+ *
+ * `id` is stable and app-scoped (`events`, `attempt-transcripts`), because it is
+ * the override key — renaming one silently orphans the owner's setting, which is
+ * why `retentionPolicies.test.ts` pins the ids too.
+ */
+export interface RetentionDeclaration {
+	/** App key, matching the fleet registry's app-tracking rows (`orch`, `notes`, …). */
+	app: string;
+	/** Stable, app-scoped id. The override key is `<app>:<id>`. */
+	id: string;
+	/** Human label for the UI. */
+	label: string;
+	category: RetentionCategory;
+	unit: RetentionUnit;
+	/** Where it physically lives, for the UI: `orch.sqlite · events`, `logs/attempts/*.jsonl`. */
+	location: string;
+	/** One sentence: what is lost when this ages out. The UI shows it beside the control. */
+	consequence: string;
+	/** Defaults to the category's `defaultDays`. */
+	defaultDays?: number;
+	/**
+	 * Absolute item-count backstop, liveness ignored, applied after the age
+	 * sweep. `0` disables it. This is the bound that must hold when the age sweep
+	 * cannot — a runaway loop writing rows against one live task is the realistic
+	 * way that happens. A bound that politely declines to bind is not a bound.
+	 */
+	defaultMaxItems?: number;
+	/**
+	 * Byte budget for the resource, applied like `defaultMaxItems` but measured in
+	 * size — the right bound when items vary by orders of magnitude, which is why
+	 * `orch`'s worker transcripts use it (one deep run can be 5 MB, one trivial
+	 * attempt 4 KB, so a count cap bounds nothing useful). `0` disables it.
+	 * Honored by targets that can measure bytes; a sqlite-table target ignores it.
+	 */
+	defaultMaxBytes?: number;
+	/**
+	 * Never delete the newest N, at any age, for any reason — the rule that makes
+	 * an unattended sweep safe (learned in `deploy-engine/backupRetention.ts`: a
+	 * naive age rule deletes every artifact of an app that stopped being
+	 * deployed). A resource with a floor converges to the floor and stays there.
+	 */
+	floorItems?: number;
+	/** Narrowed bounds for this resource's override. */
+	minDays?: number;
+	maxDays?: number;
+}
+
+/** The owner's per-resource change, made in the station UI. */
+export interface RetentionOverride {
+	days?: number;
+	maxItems?: number;
+	maxBytes?: number;
+	/** `false` suspends the sweep and keeps everything — deliberate, and shown as such. */
+	enabled?: boolean;
+	note?: string;
+	updatedAt?: number;
+	updatedBy?: string;
+}
+
+export type RetentionFieldSource = "default" | "override";
+
+/**
+ * The fleet's canonical `RetentionPolicy` — an alias for the resolved,
+ * in-effect policy a sweep runs with. Named here (DEDUP-8(c)) so exactly one
+ * module owns the word: the billing/audit WINDOWS carry `RetentionWindows` and
+ * backup pruning carries `BackupRetentionPolicy`, both deliberately distinct.
+ */
+export type RetentionPolicy = EffectiveRetentionPolicy;
+
+/** What a sweep actually runs with, plus where each number came from. */
+export interface EffectiveRetentionPolicy {
+	key: string;
+	app: string;
+	id: string;
+	enabled: boolean;
+	/** Age cutoff in days. `0` means the age sweep is off (the cap may still apply). */
+	days: number;
+	maxItems: number;
+	maxBytes: number;
+	floorItems: number;
+	minDays: number;
+	maxDays: number;
+	sources: {
+		days: RetentionFieldSource;
+		maxItems: RetentionFieldSource;
+		maxBytes: RetentionFieldSource;
+		enabled: RetentionFieldSource;
+	};
+	/** Set when an override asked for something out of bounds and was clamped. */
+	clamped?: { field: "days" | "maxItems" | "maxBytes"; requested: number; applied: number };
+}
+
+/** The override key. One function so the UI, the store and the sweeper agree. */
+export function retentionKey(app: string, id: string): string {
+	return `${app}:${id}`;
+}
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Reject a malformed declaration at construction rather than at sweep time — a
+ * resource whose id cannot be an override key is a control the owner would
+ * change with no effect.
+ */
+export function assertRetentionDeclaration(declaration: RetentionDeclaration): void {
+	const { app, id } = declaration;
+	if (!ID_PATTERN.test(app)) throw new Error(`retention: app key "${app}" must be lower-kebab`);
+	if (!ID_PATTERN.test(id)) throw new Error(`retention: resource id "${id}" must be lower-kebab`);
+	if (!(declaration.category in RETENTION_CATEGORIES)) {
+		throw new Error(
+			`retention: "${retentionKey(app, id)}" declares unknown category "${declaration.category}". ` +
+				`Retention is opt-in by category (${RETENTION_CATEGORY_KEYS.join(", ")}); data that fits ` +
+				"none of them must not be swept.",
+		);
+	}
+	if (!declaration.consequence.trim()) {
+		throw new Error(
+			`retention: "${retentionKey(app, id)}" must say what is lost when it ages out — the owner ` +
+				"reads that sentence before changing the number.",
+		);
+	}
+	for (const [field, value] of [
+		["defaultDays", declaration.defaultDays],
+		["defaultMaxItems", declaration.defaultMaxItems],
+		["defaultMaxBytes", declaration.defaultMaxBytes],
+		["floorItems", declaration.floorItems],
+	] as const) {
+		if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+			throw new Error(
+				`retention: "${retentionKey(app, id)}" ${field} must be a non-negative number`,
+			);
+		}
+	}
+}
+
+const clamp = (value: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, value));
+
+/**
+ * Merge a declaration with the owner's override into the numbers a sweep runs
+ * with. Pure, so both the sweeper and the UI's "what would this delete?" preview
+ * resolve identically — a preview computed by different code than the sweep is a
+ * preview that can lie.
+ *
+ * `days: 0` is preserved rather than clamped up to `minDays`: it is the explicit
+ * "keep forever" the UI offers, and clamping it would silently re-arm a sweep the
+ * owner turned off.
+ */
+export function resolveRetentionPolicy(
+	declaration: RetentionDeclaration,
+	override?: RetentionOverride | null,
+): EffectiveRetentionPolicy {
+	assertRetentionDeclaration(declaration);
+	const category = RETENTION_CATEGORIES[declaration.category];
+	const minDays = declaration.minDays ?? RETENTION_MIN_DAYS;
+	const maxDays = declaration.maxDays ?? RETENTION_MAX_DAYS;
+	const defaultDays = declaration.defaultDays ?? category.defaultDays;
+
+	let days = defaultDays;
+	let daysSource: RetentionFieldSource = "default";
+	let clamped: EffectiveRetentionPolicy["clamped"];
+	if (typeof override?.days === "number" && Number.isFinite(override.days)) {
+		const requested = Math.round(override.days);
+		const applied = requested === 0 ? 0 : clamp(requested, minDays, maxDays);
+		if (applied !== requested) clamped = { field: "days", requested, applied };
+		days = applied;
+		daysSource = "override";
+	}
+
+	let maxItems = declaration.defaultMaxItems ?? 0;
+	let maxItemsSource: RetentionFieldSource = "default";
+	if (typeof override?.maxItems === "number" && Number.isFinite(override.maxItems)) {
+		const requested = Math.round(override.maxItems);
+		const applied = Math.max(0, requested);
+		if (applied !== requested) clamped = { field: "maxItems", requested, applied };
+		maxItems = applied;
+		maxItemsSource = "override";
+	}
+
+	let maxBytes = declaration.defaultMaxBytes ?? 0;
+	let maxBytesSource: RetentionFieldSource = "default";
+	if (typeof override?.maxBytes === "number" && Number.isFinite(override.maxBytes)) {
+		const requested = Math.round(override.maxBytes);
+		const applied = Math.max(0, requested);
+		if (applied !== requested) clamped = { field: "maxBytes", requested, applied };
+		maxBytes = applied;
+		maxBytesSource = "override";
+	}
+
+	const enabled = override?.enabled ?? true;
+
+	return {
+		key: retentionKey(declaration.app, declaration.id),
+		app: declaration.app,
+		id: declaration.id,
+		enabled,
+		days,
+		maxItems,
+		maxBytes,
+		floorItems: declaration.floorItems ?? 0,
+		minDays,
+		maxDays,
+		sources: {
+			days: daysSource,
+			maxItems: maxItemsSource,
+			maxBytes: maxBytesSource,
+			enabled: override?.enabled === undefined ? "default" : "override",
+		},
+		...(clamped ? { clamped } : {}),
+	};
+}
+
+export const DAY_MS = 86_400_000;
+
+/** The age cutoff a sweep compares against, or `null` when the age sweep is off. */
+export function cutoffFor(policy: EffectiveRetentionPolicy, now: number): number | null {
+	if (!policy.enabled || policy.days <= 0) return null;
+	return now - policy.days * DAY_MS;
+}