cursedbelt 2.8.0 → 3.0.0

package/src/server/retention/index.ts

@@ -1,101 +0,0 @@
-/**
- * `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/server/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

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

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