cursedbelt-server 1.0.0

package/dist/server/retention/policy.d.ts

@@ -0,0 +1,263 @@
+/**
+ * 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 declare const RETENTION_CATEGORIES: {
+    readonly "audit-log": {
+        readonly label: "Audit log";
+        readonly defaultDays: 14;
+        readonly summary: "Who did what, kept so an incident can be reconstructed. Read only after a problem.";
+    };
+    readonly "event-log": {
+        readonly label: "Event log";
+        readonly defaultDays: 14;
+        readonly summary: "State transitions and activity trails. The narrative of a run, not the run's result.";
+    };
+    readonly "run-log": {
+        readonly label: "Run log";
+        readonly defaultDays: 14;
+        readonly summary: "One row per execution of a job, check or sweep — its outcome ledger.";
+    };
+    readonly transcript: {
+        readonly label: "Transcript";
+        readonly defaultDays: 14;
+        readonly summary: "Verbatim worker/tool output. Large, read once during triage, never again.";
+    };
+    readonly metric: {
+        readonly label: "Metric";
+        readonly defaultDays: 14;
+        readonly summary: "Sampled counters and telemetry. Interesting in aggregate and recent, not per-row.";
+    };
+    readonly cache: {
+        readonly label: "Cache";
+        readonly defaultDays: 7;
+        readonly summary: "Recomputable from its source. Shorter by default because losing it costs a refetch.";
+    };
+    readonly "replica-mirror": {
+        readonly label: "Replica mirror";
+        readonly defaultDays: 7;
+        readonly summary: "A copy of state that another instance owns authoritatively. Never the only copy.";
+    };
+    readonly "queue-result": {
+        readonly label: "Queue result";
+        readonly defaultDays: 3;
+        readonly summary: "Completed command/job rows and their payloads, kept only long enough to answer a retry or a replay.";
+    };
+    readonly "scratch-artifact": {
+        readonly label: "Scratch artifact";
+        readonly defaultDays: 14;
+        readonly summary: "Generated files kept for inspection — renders, dumps, exports. Reproducible by rerunning.";
+    };
+    readonly "archived-history": {
+        readonly label: "Archived history";
+        readonly defaultDays: 30;
+        readonly archivesBeforeDelete: true;
+        readonly 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.";
+    };
+};
+export type RetentionCategory = keyof typeof RETENTION_CATEGORIES;
+export declare const RETENTION_CATEGORY_KEYS: 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 declare function categoryArchivesBeforeDelete(category: RetentionCategory): boolean;
+/** The categories whose rows are archived rather than destroyed. */
+export declare const ARCHIVING_RETENTION_CATEGORIES: ("audit-log" | "event-log" | "run-log" | "transcript" | "metric" | "cache" | "replica-mirror" | "queue-result" | "scratch-artifact" | "archived-history")[];
+/**
+ * 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 declare const FLEET_DEFAULT_RETENTION_DAYS = 14;
+/** Bounds an override is clamped into unless a declaration narrows them. */
+export declare const RETENTION_MIN_DAYS = 1;
+export declare 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 declare function retentionKey(app: string, id: string): string;
+/**
+ * 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 declare function assertRetentionDeclaration(declaration: RetentionDeclaration): void;
+/**
+ * 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 declare function resolveRetentionPolicy(declaration: RetentionDeclaration, override?: RetentionOverride | null): EffectiveRetentionPolicy;
+export declare const DAY_MS = 86400000;
+/** The age cutoff a sweep compares against, or `null` when the age sweep is off. */
+export declare function cutoffFor(policy: EffectiveRetentionPolicy, now: number): number | null;

package/dist/server/retention/policy.js

@@ -0,0 +1,264 @@
+/**
+ * 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.",
+    },
+};
+export const RETENTION_CATEGORY_KEYS = Object.keys(RETENTION_CATEGORIES);
+/**
+ * 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) {
+    // 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];
+    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;
+/** The override key. One function so the UI, the store and the sweeper agree. */
+export function retentionKey(app, id) {
+    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) {
+    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],
+    ]) {
+        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, lo, hi) => 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, override) {
+    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 = "default";
+    let 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 = "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 = "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, now) {
+    if (!policy.enabled || policy.days <= 0)
+        return null;
+    return now - policy.days * DAY_MS;
+}

package/dist/server/retention/store.d.ts

@@ -0,0 +1,101 @@
+import type { RetentionDeclaration, RetentionOverride } from "./policy";
+/** What one sweep of one resource did. Published so the UI can show it. */
+export interface RetentionSweepReport {
+    at: number;
+    /** Items removed because they aged past the cutoff. */
+    aged: number;
+    /** Items removed by the item-count backstop, liveness ignored. */
+    overflow: number;
+    /**
+     * Items the sweep deliberately left alone because they are still live — a
+     * running worker's transcript, an unsettled task's trail. Reported so a
+     * resource that stays large has an explanation rather than looking like a
+     * broken sweep.
+     */
+    protectedItems?: number;
+    bytesFreed?: number;
+    /**
+     * Items written to the archive before they were deleted — the `archived-history`
+     * category's receipt. Reported so the station can show "moved" rather than
+     * "removed": for an archiving resource those two words are the whole difference,
+     * and a UI that said the second would be describing data loss that did not happen.
+     */
+    archived?: number;
+    /** Bytes those archived items occupy in the archive. */
+    archivedBytes?: number;
+    /**
+     * Why this sweep deliberately removed nothing, when it otherwise would have.
+     * An archiving resource whose archive is not being collected REFUSES to trim,
+     * and a resource that quietly stops working is indistinguishable from one with
+     * nothing to do — so the reason is carried out to the UI rather than logged and
+     * lost.
+     */
+    blocked?: string;
+    error?: string;
+}
+/** A live measurement of a resource, taken at sweep time. */
+export interface RetentionMeasurement {
+    items: number;
+    bytes?: number;
+    /** Timestamp of the oldest item, when the target can report it cheaply. */
+    oldestAt?: number;
+}
+/** One resource as published by its owning app. */
+export interface PublishedResource {
+    declaration: RetentionDeclaration;
+    measurement?: RetentionMeasurement;
+    lastSweep?: RetentionSweepReport;
+}
+/** One app's publication file. */
+export interface RetentionPublication {
+    app: string;
+    version: 1;
+    publishedAt: number;
+    /** The instance that published — `local`, `prod`, `dev`; purely informational. */
+    instance?: string;
+    /** True when the process that published it has sweeping disabled entirely. */
+    sweepDisabled?: boolean;
+    resources: PublishedResource[];
+}
+export interface RetentionOverridesFile {
+    version: 1;
+    updatedAt: number;
+    /** Keyed by `<app>:<id>` — `retentionKey()`. */
+    overrides: Record<string, RetentionOverride>;
+}
+/**
+ * Resolve the retention home. See the module note for the ordering rationale.
+ * Cached per process — it is consulted on every sweep and cannot change under a
+ * running app.
+ */
+export declare function resolveRetentionHome(env?: Record<string, string | undefined>): string;
+/** Test seam — point the home somewhere else for this process. */
+export declare function setRetentionHomeForTests(home: string | null): void;
+/**
+ * Publish one app's resources. Best-effort by contract: a retention publication
+ * that cannot be written is a missing row in a dashboard, and must never take
+ * down the app that owns the data.
+ */
+export declare function publishRetention(publication: Omit<RetentionPublication, "version" | "publishedAt">, options?: {
+    home?: string;
+    log?: (line: string) => void;
+}): boolean;
+/** Every app's publication, newest-published first. */
+export declare function readRetentionRegistry(home?: string): RetentionPublication[];
+export declare function readRetentionOverrides(home?: string): RetentionOverridesFile;
+/**
+ * Apply one override. Read-modify-write, so an unrelated resource's setting is
+ * never lost to a concurrent edit of this one; the station is the only writer,
+ * which is what keeps that honest.
+ *
+ * A patch field set to `undefined` is left alone; set to `null` it is CLEARED,
+ * which is how the UI's "reset to default" works — deleting the key is the only
+ * way to make the declaration's default authoritative again, since a stored
+ * value that merely equals the default would freeze the resource at today's
+ * number if the default ever moves.
+ */
+export declare function writeRetentionOverride(app: string, id: string, patch: Partial<Record<"days" | "maxItems" | "maxBytes" | "enabled" | "note", unknown>> | null, options?: {
+    home?: string;
+    updatedBy?: string;
+    now?: number;
+}): RetentionOverridesFile;