knodin 0.8.7 → 0.9.0

package/dist/src/backup-retention.js

@@ -0,0 +1,811 @@
+import childProcess from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import { acquireRepairLease } from "./repair-lease.js";
+const BACKUP = /^db\.sqlite\.backup\.(\d{13})\.([0-9a-f]{8})$/;
+const PRUNED_DIRECTORIES = new Set([
+    ".git",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".venv",
+    ".next",
+    "vendor",
+]);
+const DAY_MS = 86_400_000;
+function homes(options = {}) {
+    const home = options.homeDir ?? os.homedir();
+    const configHome = path.resolve(options.configHome ?? process.env.XDG_CONFIG_HOME ?? path.join(home, ".config"));
+    const stateHome = path.resolve(options.stateHome ?? process.env.XDG_STATE_HOME ?? path.join(home, ".local", "state"));
+    return {
+        home,
+        configHome,
+        stateHome,
+        policy: path.join(configHome, "knodin", "backup-retention.json"),
+        stateRoot: path.join(stateHome, "knodin", "backup-retention"),
+    };
+}
+function canonicalDirectory(candidate) {
+    try {
+        const stat = fs.lstatSync(candidate);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return null;
+        return fs.realpathSync(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+function registryPaths(configHome) {
+    try {
+        const parsed = YAML.parse(fs.readFileSync(path.join(configHome, "knodin", "repositories.yaml"), "utf8"));
+        return Object.values(parsed?.repositories ?? {}).flatMap((value) => typeof value === "string" && path.isAbsolute(value) ? [value] : []);
+    }
+    catch {
+        return [];
+    }
+}
+function isRepository(candidate) {
+    try {
+        const state = fs.lstatSync(path.join(candidate, ".knodin"));
+        return state.isDirectory() && !state.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function discoverBackupRepositories(roots, options = {}) {
+    const depth = options.depth ?? 5;
+    if (!Number.isInteger(depth) || depth < 0 || depth > 32)
+        throw new Error("knodin backups: --depth must be an integer from 0 to 32");
+    const { configHome } = homes(options);
+    const repositories = new Set();
+    const issues = [];
+    const walk = (directory, remaining) => {
+        const canonical = canonicalDirectory(directory);
+        if (!canonical) {
+            issues.push({ repository: path.resolve(directory), reason: "missing-or-unsafe-root" });
+            return;
+        }
+        if (isRepository(canonical))
+            repositories.add(canonical);
+        if (remaining === 0)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(canonical, { withFileTypes: true });
+        }
+        catch (error) {
+            issues.push({ repository: canonical, reason: `unreadable-root: ${message(error)}` });
+            return;
+        }
+        const orderedEntries = [...entries];
+        orderedEntries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of orderedEntries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink() || PRUNED_DIRECTORIES.has(entry.name))
+                continue;
+            walk(path.join(canonical, entry.name), remaining - 1);
+        }
+    };
+    for (const root of roots)
+        walk(path.resolve(root), depth);
+    if (options.includeRegistry) {
+        for (const registered of registryPaths(configHome)) {
+            const canonical = canonicalDirectory(registered);
+            if (canonical && isRepository(canonical))
+                repositories.add(canonical);
+        }
+    }
+    return { repositories: [...repositories].sort((a, b) => a.localeCompare(b)), issues };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function inventory(repository) {
+    const stateRoot = path.join(repository, ".knodin");
+    const backups = [];
+    const skipped = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        return { backups, skipped: [{ repository, reason: `inventory-failed: ${message(error)}` }] };
+    }
+    for (const entry of entries) {
+        const match = BACKUP.exec(entry.name);
+        if (!match)
+            continue;
+        const target = path.join(stateRoot, entry.name);
+        try {
+            const stat = fs.lstatSync(target);
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                skipped.push({ repository, path: target, reason: "not-a-regular-file" });
+                continue;
+            }
+            const timestamp = Number(match[1]);
+            backups.push({
+                repository,
+                path: target,
+                createdAt: new Date(timestamp).toISOString(),
+                timestamp,
+                bytes: stat.size,
+                device: stat.dev,
+                inode: stat.ino,
+                modifiedAtMs: stat.mtimeMs,
+            });
+        }
+        catch (error) {
+            skipped.push({ repository, path: target, reason: `stat-failed: ${message(error)}` });
+        }
+    }
+    backups.sort((a, b) => b.timestamp - a.timestamp || a.path.localeCompare(b.path));
+    return { backups, skipped };
+}
+export function listBackups(roots, options = {}) {
+    const discovery = discoverBackupRepositories(roots, options);
+    const backups = [];
+    const skipped = [...discovery.issues];
+    for (const repository of discovery.repositories) {
+        const found = inventory(repository);
+        backups.push(...found.backups);
+        skipped.push(...found.skipped);
+    }
+    backups.sort((a, b) => a.repository.localeCompare(b.repository) || b.timestamp - a.timestamp);
+    return {
+        schemaVersion: 1,
+        repositories: discovery.repositories,
+        backups,
+        count: backups.length,
+        totalBytes: backups.reduce((sum, entry) => sum + entry.bytes, 0),
+        skipped,
+    };
+}
+function safeLiveDatabase(repository) {
+    const statePath = path.join(repository, ".knodin");
+    const stateStat = fs.lstatSync(statePath);
+    if (!stateStat.isDirectory() || stateStat.isSymbolicLink())
+        return null;
+    const stateRoot = fs.realpathSync(statePath);
+    const live = path.join(stateRoot, "db.sqlite");
+    const stat = fs.lstatSync(live);
+    if (!stat.isFile() || stat.isSymbolicLink() || path.dirname(fs.realpathSync(live)) !== stateRoot)
+        return null;
+    const descriptor = fs.openSync(live, "r");
+    try {
+        const header = Buffer.alloc(16);
+        if (fs.readSync(descriptor, header, 0, header.length, 0) !== header.length)
+            return null;
+        if (!header.equals(Buffer.from("SQLite format 3\0", "binary")))
+            return null;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    return live;
+}
+function markerExists(target) {
+    try {
+        fs.lstatSync(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function pruneBackups(roots, options = {}) {
+    const now = options.now ?? new Date();
+    const retentionDays = options.retentionDays ?? 3;
+    const keepNewest = options.keepNewest ?? 1;
+    if (!Number.isInteger(retentionDays) || retentionDays < 0 || retentionDays > 3650)
+        throw new Error("knodin backups: --retention-days must be an integer from 0 to 3650");
+    if (!Number.isInteger(keepNewest) || keepNewest < 0 || keepNewest > 1000)
+        throw new Error("knodin backups: --keep-newest must be an integer from 0 to 1000");
+    const listed = listBackups(roots, options);
+    const cutoff = now.getTime() - retentionDays * DAY_MS;
+    const candidates = [];
+    const deleted = [];
+    const skipped = [...listed.skipped];
+    for (const repository of listed.repositories) {
+        const repositoryBackups = listed.backups.filter((entry) => entry.repository === repository);
+        const planned = repositoryBackups.slice(keepNewest).filter((entry) => entry.timestamp < cutoff);
+        candidates.push(...planned);
+        if (!options.apply || planned.length === 0)
+            continue;
+        let lease;
+        try {
+            lease = acquireRepairLease(repository, "backups prune");
+            const marker = path.join(repository, ".knodin", "promotion.json");
+            if (markerExists(marker))
+                throw new Error("promotion-in-progress-or-malformed-marker");
+            if (!safeLiveDatabase(repository))
+                throw new Error("missing-or-unsafe-live-database");
+            const stateRoot = fs.realpathSync(path.join(repository, ".knodin"));
+            for (const candidate of planned) {
+                try {
+                    const name = path.basename(candidate.path);
+                    if (!BACKUP.test(name) || path.dirname(candidate.path) !== stateRoot)
+                        throw new Error("candidate-containment-changed");
+                    const stat = fs.lstatSync(candidate.path);
+                    if (!stat.isFile() ||
+                        stat.isSymbolicLink() ||
+                        stat.size !== candidate.bytes ||
+                        stat.dev !== candidate.device ||
+                        stat.ino !== candidate.inode ||
+                        stat.mtimeMs !== candidate.modifiedAtMs)
+                        throw new Error("candidate-changed-after-plan");
+                    fs.unlinkSync(candidate.path);
+                    deleted.push(candidate);
+                }
+                catch (error) {
+                    skipped.push({ repository, path: candidate.path, reason: message(error) });
+                }
+            }
+        }
+        catch (error) {
+            skipped.push({ repository, reason: message(error) });
+        }
+        finally {
+            lease?.release();
+        }
+    }
+    return {
+        schemaVersion: 1,
+        mode: options.apply ? "apply" : "preview",
+        retentionDays,
+        keepNewest,
+        candidates,
+        candidateCount: candidates.length,
+        reclaimableBytes: candidates.reduce((sum, entry) => sum + entry.bytes, 0),
+        deleted,
+        deletedBytes: deleted.reduce((sum, entry) => sum + entry.bytes, 0),
+        skipped,
+    };
+}
+function digest(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function atomicWrite(target, content, mode = 0o600) {
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.tmp-${process.pid}-${crypto.randomUUID()}`;
+    fs.writeFileSync(temporary, content, { mode, flag: "wx" });
+    fs.renameSync(temporary, target);
+}
+function readJson(target) {
+    try {
+        return JSON.parse(fs.readFileSync(target, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function exactKeys(value, keys) {
+    const alphabetically = (left, right) => left.localeCompare(right);
+    return (Object.keys(value).sort(alphabetically).join("\0") === [...keys].sort(alphabetically).join("\0"));
+}
+function parseRetentionPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!exactKeys(record, [
+        "schemaVersion",
+        "installedAt",
+        "roots",
+        "retentionDays",
+        "keepNewest",
+        "depth",
+        "schedule",
+        "launcher",
+        "dryRun",
+    ]) ||
+        record.schemaVersion !== 1 ||
+        typeof record.installedAt !== "string" ||
+        !Number.isFinite(Date.parse(record.installedAt)) ||
+        !Array.isArray(record.roots) ||
+        record.roots.length === 0 ||
+        !record.roots.every((root) => typeof root === "string" && path.isAbsolute(root)) ||
+        !Number.isInteger(record.retentionDays) ||
+        record.retentionDays < 0 ||
+        record.retentionDays > 3650 ||
+        !Number.isInteger(record.keepNewest) ||
+        record.keepNewest < 0 ||
+        record.keepNewest > 1000 ||
+        !Number.isInteger(record.depth) ||
+        record.depth < 0 ||
+        record.depth > 32 ||
+        typeof record.schedule !== "string" ||
+        !/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(record.schedule) ||
+        !Array.isArray(record.launcher) ||
+        record.launcher.length === 0 ||
+        !record.launcher.every((part) => typeof part === "string") ||
+        !path.isAbsolute(record.launcher[0]) ||
+        typeof record.dryRun !== "boolean")
+        return null;
+    return record;
+}
+function parseRetentionReceipt(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!exactKeys(record, ["schemaVersion", "platform", "installedAt", "policyDigest", "artifacts"]) ||
+        record.schemaVersion !== 1 ||
+        !["darwin", "linux", "win32"].includes(record.platform) ||
+        typeof record.installedAt !== "string" ||
+        !Number.isFinite(Date.parse(record.installedAt)) ||
+        typeof record.policyDigest !== "string" ||
+        !/^[0-9a-f]{64}$/.test(record.policyDigest) ||
+        !Array.isArray(record.artifacts) ||
+        record.artifacts.length === 0 ||
+        !record.artifacts.every((artifact) => artifact &&
+            typeof artifact === "object" &&
+            !Array.isArray(artifact) &&
+            exactKeys(artifact, ["path", "digest"]) &&
+            typeof artifact.path === "string" &&
+            path.isAbsolute(artifact.path) &&
+            typeof artifact.digest === "string" &&
+            /^[0-9a-f]{64}$/.test(artifact.digest)))
+        return null;
+    return record;
+}
+function readInstalledRetention(options) {
+    const locations = homes(options);
+    const policy = parseRetentionPolicy(readJson(locations.policy));
+    const receipt = parseRetentionReceipt(readJson(path.join(locations.stateRoot, "receipt.json")));
+    const issues = [];
+    if (!policy)
+        issues.push("policy-missing-or-invalid");
+    if (!receipt)
+        issues.push("receipt-missing-or-invalid");
+    if (policy && receipt && digest(`${JSON.stringify(policy, null, 2)}\n`) !== receipt.policyDigest)
+        issues.push("policy-receipt-mismatch");
+    for (const artifact of receipt?.artifacts ?? []) {
+        try {
+            if (digest(fs.readFileSync(artifact.path, "utf8")) !== artifact.digest)
+                issues.push(`scheduler-content-mismatch: ${artifact.path}`);
+        }
+        catch {
+            issues.push(`scheduler-missing: ${artifact.path}`);
+        }
+    }
+    return { policy, receipt, issues };
+}
+function commandRunner(command, args) {
+    const result = childProcess.spawnSync(command, args, { encoding: "utf8" });
+    return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+function schedulerArtifacts(policy, options) {
+    const { home, stateRoot } = homes(options);
+    const platform = options.platform ?? process.platform;
+    const command = [...policy.launcher, "backups", "retention", "run", "--json"];
+    if (platform === "darwin") {
+        const [hour, minute] = policy.schedule.split(":").map(Number);
+        const argumentsXml = command.map((value) => `<string>${escapeXml(value)}</string>`).join("");
+        return [
+            {
+                path: path.join(home, "Library", "LaunchAgents", "dev.knodin.backup-retention.plist"),
+                content: `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>dev.knodin.backup-retention</string><key>ProgramArguments</key><array>${argumentsXml}</array><key>RunAtLoad</key><true/><key>StartCalendarInterval</key><dict><key>Hour</key><integer>${hour}</integer><key>Minute</key><integer>${minute}</integer></dict><key>StandardOutPath</key><string>${escapeXml(path.join(stateRoot, "scheduler.log"))}</string><key>StandardErrorPath</key><string>${escapeXml(path.join(stateRoot, "scheduler.log"))}</string></dict></plist>\n`,
+            },
+        ];
+    }
+    if (platform === "win32") {
+        const executable = command[0] ?? "knodin";
+        const args = command.slice(1).map(windowsQuote).join(" ");
+        return [
+            {
+                path: path.join(stateRoot, "dev.knodin.backup-retention.xml"),
+                content: `<?xml version="1.0" encoding="UTF-8"?>\n<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task"><Triggers><CalendarTrigger><StartBoundary>2000-01-01T${policy.schedule}:00</StartBoundary><ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay></CalendarTrigger><LogonTrigger/></Triggers><Settings><StartWhenAvailable>true</StartWhenAvailable></Settings><Actions Context="Author"><Exec><Command>${escapeXml(executable)}</Command><Arguments>${escapeXml(args)}</Arguments></Exec></Actions></Task>\n`,
+            },
+        ];
+    }
+    const service = `[Unit]\nDescription=Knodin backup retention\n[Service]\nType=oneshot\nExecStart=${command.map(systemdQuote).join(" ")}\n`;
+    const timer = `[Unit]\nDescription=Daily Knodin backup retention\n[Timer]\nOnCalendar=*-*-* ${policy.schedule}:00\nPersistent=true\n[Install]\nWantedBy=timers.target\n`;
+    const systemd = path.join(home, ".config", "systemd", "user");
+    return [
+        { path: path.join(systemd, "knodin-backup-retention.service"), content: service },
+        { path: path.join(systemd, "knodin-backup-retention.timer"), content: timer },
+    ];
+}
+function escapeXml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function systemdQuote(value) {
+    return value.replaceAll("%", "%%").replace(/([\\\s"'])/g, "\\$1");
+}
+function windowsQuote(value) {
+    return `"${value.replaceAll('"', '\\"')}"`;
+}
+function validateSchedule(value) {
+    if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(value))
+        throw new Error("knodin backups retention: --schedule must be HH:MM local time");
+    return value;
+}
+function schedulerRun(platform, action, run, artifacts) {
+    const checked = (command, args) => {
+        const result = run(command, args);
+        if (result.status !== 0)
+            throw new Error(`knodin backups retention: scheduler command failed (${command} ${args.join(" ")}): ${result.stderr || result.stdout || `exit ${result.status}`}`);
+        return result;
+    };
+    if (platform === "darwin") {
+        const target = artifacts[0]?.path;
+        if (target)
+            checked("launchctl", [action === "install" ? "load" : "unload", target]);
+    }
+    else if (platform === "linux") {
+        checked("systemctl", ["--user", "daemon-reload"]);
+        checked("systemctl", [
+            "--user",
+            action === "install" ? "enable" : "disable",
+            "--now",
+            "knodin-backup-retention.timer",
+        ]);
+    }
+    else if (platform === "win32") {
+        if (action === "install")
+            checked("schtasks", [
+                "/Create",
+                "/TN",
+                "Knodin Backup Retention",
+                "/XML",
+                artifacts[0]?.path ?? "",
+                "/F",
+            ]);
+        else
+            checked("schtasks", ["/Delete", "/TN", "Knodin Backup Retention", "/F"]);
+    }
+}
+export function installBackupRetention(roots, options = {}) {
+    const discovered = discoverBackupRepositories(roots, { ...options, includeRegistry: true });
+    if (discovered.repositories.length === 0)
+        throw new Error("knodin backups retention install: no repositories found in roots or registry");
+    if (options.retentionDays !== undefined &&
+        (!Number.isInteger(options.retentionDays) ||
+            options.retentionDays < 0 ||
+            options.retentionDays > 3650))
+        throw new Error("knodin backups retention: --retention-days must be an integer from 0 to 3650");
+    if (options.keepNewest !== undefined &&
+        (!Number.isInteger(options.keepNewest) || options.keepNewest < 0 || options.keepNewest > 1000))
+        throw new Error("knodin backups retention: --keep-newest must be an integer from 0 to 1000");
+    const { policy: policyPath, stateRoot } = homes(options);
+    const now = new Date();
+    const launcher = (options.launcher ?? [process.execPath]).map((entry, index) => index === 0 ? path.resolve(entry) : entry);
+    const policy = {
+        schemaVersion: 1,
+        installedAt: now.toISOString(),
+        roots: [
+            ...new Set([
+                ...roots.map((root) => path.resolve(root)),
+                ...registryPaths(homes(options).configHome).flatMap((entry) => {
+                    const canonical = canonicalDirectory(entry);
+                    return canonical && isRepository(canonical) ? [canonical] : [];
+                }),
+            ]),
+        ].sort((a, b) => a.localeCompare(b)),
+        retentionDays: options.retentionDays ?? 3,
+        keepNewest: options.keepNewest ?? 1,
+        depth: options.depth ?? 5,
+        schedule: validateSchedule(options.schedule ?? "04:17"),
+        launcher,
+        dryRun: options.dryRun ?? false,
+    };
+    const platform = options.platform ?? process.platform;
+    if (!["darwin", "linux", "win32"].includes(platform))
+        throw new Error(`knodin backups retention: scheduler unsupported on ${platform}`);
+    const previousInstalled = readInstalledRetention(options);
+    const previous = previousInstalled.issues.length === 0 ? previousInstalled.receipt : null;
+    const artifacts = schedulerArtifacts(policy, options);
+    const run = options.run ?? commandRunner;
+    if (platform === "win32") {
+        const registered = run("schtasks", ["/Query", "/TN", "Knodin Backup Retention", "/XML"]);
+        if (registered.status === 0 && !previous)
+            throw new Error("knodin backups retention: refusing unmanaged Scheduled Task collision");
+    }
+    for (const artifact of artifacts) {
+        if (!fs.existsSync(artifact.path))
+            continue;
+        const existingDigest = digest(fs.readFileSync(artifact.path, "utf8"));
+        const managed = previous?.artifacts.some((record) => record.path === artifact.path && record.digest === existingDigest);
+        if (!managed)
+            throw new Error(`knodin backups retention: refusing unmanaged collision at ${artifact.path}`);
+    }
+    const policyContent = `${JSON.stringify(policy, null, 2)}\n`;
+    const receiptPath = path.join(stateRoot, "receipt.json");
+    const previousFiles = new Map();
+    for (const target of [policyPath, receiptPath, ...artifacts.map((artifact) => artifact.path)]) {
+        try {
+            previousFiles.set(target, fs.readFileSync(target, "utf8"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            previousFiles.set(target, null);
+        }
+    }
+    atomicWrite(policyPath, policyContent);
+    for (const artifact of artifacts)
+        atomicWrite(artifact.path, artifact.content, artifact.mode);
+    const receipt = {
+        schemaVersion: 1,
+        platform,
+        installedAt: now.toISOString(),
+        policyDigest: digest(policyContent),
+        artifacts: artifacts.map((artifact) => ({
+            path: artifact.path,
+            digest: digest(artifact.content),
+        })),
+    };
+    atomicWrite(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+    try {
+        schedulerRun(platform, "install", run, receipt.artifacts);
+    }
+    catch (error) {
+        for (const [target, content] of previousFiles) {
+            if (content === null)
+                fs.rmSync(target, { force: true });
+            else
+                atomicWrite(target, content);
+        }
+        if (previous) {
+            try {
+                schedulerRun(previous.platform, "install", run, previous.artifacts);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], "knodin backups retention: install and rollback reload failed");
+            }
+        }
+        throw error;
+    }
+    return {
+        schemaVersion: 1,
+        installed: true,
+        policy,
+        receipt,
+        repositories: discovered.repositories,
+    };
+}
+export function retentionStatus(options = {}) {
+    const locations = homes(options);
+    const { policy, receipt, issues } = readInstalledRetention(options);
+    const lastRun = readJson(path.join(locations.stateRoot, "last-run.json"));
+    return {
+        schemaVersion: 1,
+        status: issues.length === 0 ? "healthy" : policy || receipt ? "attention-required" : "not-installed",
+        installed: Boolean(policy && receipt),
+        policy,
+        receipt,
+        lastRun,
+        issues,
+        remediation: issues.length
+            ? "Run `knodin backups retention doctor`, then reinstall or remove retention."
+            : null,
+    };
+}
+export function retentionDoctor(options = {}) {
+    const status = retentionStatus(options);
+    const platform = options.platform ?? process.platform;
+    const supported = ["darwin", "linux", "win32"].includes(platform);
+    const issues = [...status.issues];
+    const policy = status.policy;
+    const receipt = status.receipt;
+    if (policy && receipt) {
+        if (policy.roots.length === 0 ||
+            !Number.isInteger(policy.retentionDays) ||
+            !Number.isInteger(policy.keepNewest) ||
+            !Number.isInteger(policy.depth) ||
+            !policy.launcher[0] ||
+            !path.isAbsolute(policy.launcher[0]))
+            issues.push("policy-fields-invalid");
+        else {
+            try {
+                const executable = fs.lstatSync(policy.launcher[0]);
+                if (!executable.isFile() || executable.isSymbolicLink())
+                    issues.push("launcher-unsafe");
+                if (platform !== "win32")
+                    fs.accessSync(policy.launcher[0], fs.constants.X_OK);
+            }
+            catch {
+                issues.push("launcher-missing-or-not-executable");
+            }
+        }
+        for (const target of [
+            homes(options).policy,
+            path.join(homes(options).stateRoot, "receipt.json"),
+        ]) {
+            try {
+                if ((fs.statSync(target).mode & 0o077) !== 0)
+                    issues.push(`permissions-too-open: ${target}`);
+            }
+            catch {
+                issues.push(`unreadable: ${target}`);
+            }
+        }
+        const installedAt = Date.parse(receipt.installedAt);
+        const ranAt = typeof status.lastRun?.ranAt === "string" ? Date.parse(status.lastRun.ranAt) : Number.NaN;
+        if (Date.now() - installedAt > 2 * DAY_MS &&
+            (!Number.isFinite(ranAt) || Date.now() - ranAt > 2 * DAY_MS))
+            issues.push("last-run-stale-or-missing");
+        const logs = path.join(homes(options).stateRoot, "logs");
+        try {
+            for (const name of fs.readdirSync(logs)) {
+                const target = path.join(logs, name);
+                if (fs.statSync(target).size > 5 * 1024 * 1024)
+                    issues.push(`log-oversized: ${target}`);
+                for (const line of fs.readFileSync(target, "utf8").split("\n").filter(Boolean))
+                    JSON.parse(line);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                issues.push("logs-unreadable-or-invalid");
+        }
+        if (supported) {
+            const run = options.run ?? commandRunner;
+            let scheduler;
+            if (platform === "darwin")
+                scheduler = run("launchctl", [
+                    "print",
+                    `gui/${typeof process.getuid === "function" ? process.getuid() : 0}/dev.knodin.backup-retention`,
+                ]);
+            else if (platform === "linux")
+                scheduler = run("systemctl", ["--user", "is-enabled", "knodin-backup-retention.timer"]);
+            else
+                scheduler = run("schtasks", ["/Query", "/TN", "Knodin Backup Retention", "/XML"]);
+            if (scheduler.status !== 0)
+                issues.push("scheduler-not-loaded-or-enabled");
+        }
+    }
+    return {
+        ...status,
+        status: issues.length === 0 ? status.status : "attention-required",
+        issues,
+        platform,
+        schedulerSupported: supported,
+        remediation: supported
+            ? issues.length
+                ? "Repair the reported policy, launcher, scheduler, permission, run, or log issue; then reinstall if needed."
+                : null
+            : "Scheduled retention is unsupported here; one-shot preview/apply pruning remains available.",
+    };
+}
+export function removeBackupRetention(options = {}) {
+    const locations = homes(options);
+    const receiptPath = path.join(locations.stateRoot, "receipt.json");
+    const installed = readInstalledRetention(options);
+    if (!installed.policy || !installed.receipt)
+        return { schemaVersion: 1, removed: false, reason: "not-installed" };
+    if (installed.issues.length > 0)
+        return {
+            schemaVersion: 1,
+            removed: false,
+            reason: "unhealthy-installation",
+            issues: installed.issues,
+        };
+    const receipt = installed.receipt;
+    const expected = schedulerArtifacts(installed.policy, {
+        ...options,
+        platform: receipt.platform,
+    }).map((artifact) => ({ path: artifact.path, digest: digest(artifact.content) }));
+    if (receipt.artifacts.length !== expected.length ||
+        receipt.artifacts.some((artifact, index) => artifact.path !== expected[index]?.path || artifact.digest !== expected[index]?.digest))
+        return { schemaVersion: 1, removed: false, reason: "unmanaged-artifact-receipt" };
+    const skipped = [];
+    for (const artifact of receipt.artifacts) {
+        try {
+            if (digest(fs.readFileSync(artifact.path, "utf8")) !== artifact.digest)
+                skipped.push(artifact.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                skipped.push(artifact.path);
+        }
+    }
+    if (skipped.length > 0)
+        return { schemaVersion: 1, removed: false, skipped };
+    const run = options.run ?? commandRunner;
+    if (receipt.platform === "win32") {
+        const registered = run("schtasks", ["/Query", "/TN", "Knodin Backup Retention", "/XML"]);
+        if (registered.status === 0)
+            schedulerRun(receipt.platform, "remove", run, receipt.artifacts);
+    }
+    else {
+        schedulerRun(receipt.platform, "remove", run, receipt.artifacts);
+    }
+    for (const artifact of receipt.artifacts) {
+        try {
+            if (digest(fs.readFileSync(artifact.path, "utf8")) === artifact.digest)
+                fs.unlinkSync(artifact.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                skipped.push(artifact.path);
+        }
+    }
+    if (skipped.length === 0) {
+        fs.rmSync(locations.policy, { force: true });
+        fs.rmSync(receiptPath, { force: true });
+    }
+    return { schemaVersion: 1, removed: skipped.length === 0, skipped };
+}
+export function runInstalledRetention(options = {}) {
+    const locations = homes(options);
+    const installed = readInstalledRetention(options);
+    if (!installed.policy || !installed.receipt)
+        throw new Error("knodin backups retention: not installed");
+    if (installed.issues.length > 0)
+        throw new Error(`knodin backups retention: refusing unhealthy installation (${installed.issues.join(", ")})`);
+    const policy = installed.policy;
+    const result = pruneBackups(policy.roots, {
+        ...options,
+        depth: policy.depth,
+        includeRegistry: true,
+        retentionDays: policy.retentionDays,
+        keepNewest: policy.keepNewest,
+        apply: !policy.dryRun,
+    });
+    const record = { ...result, ranAt: (options.now ?? new Date()).toISOString() };
+    atomicWrite(path.join(locations.stateRoot, "last-run.json"), `${JSON.stringify(record, null, 2)}\n`);
+    appendRunLog(locations.stateRoot, record);
+    return record;
+}
+function appendRunLog(stateRoot, record) {
+    fs.mkdirSync(path.join(stateRoot, "logs"), { recursive: true, mode: 0o700 });
+    const now = new Date();
+    const cutoff = now.getTime() - 30 * DAY_MS;
+    for (const name of fs.readdirSync(path.join(stateRoot, "logs"))) {
+        const target = path.join(stateRoot, "logs", name);
+        try {
+            if (fs.statSync(target).mtimeMs < cutoff)
+                fs.unlinkSync(target);
+        }
+        catch { }
+    }
+    const target = path.join(stateRoot, "logs", `${now.toISOString().slice(0, 10)}.jsonl`);
+    fs.appendFileSync(target, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    if (fs.statSync(target).size > 5 * 1024 * 1024) {
+        const lines = fs.readFileSync(target, "utf8").trimEnd().split("\n");
+        const retained = [];
+        let bytes = 0;
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+            const line = lines[index];
+            const lineBytes = Buffer.byteLength(line) + 1;
+            if (bytes + lineBytes > 5 * 1024 * 1024)
+                break;
+            retained.unshift(line);
+            bytes += lineBytes;
+        }
+        fs.writeFileSync(target, retained.length ? `${retained.join("\n")}\n` : "", { mode: 0o600 });
+    }
+}
+export function maybeRunOpportunisticRetention(repository, options = {}) {
+    const locations = homes(options);
+    const installed = readInstalledRetention(options);
+    if (!installed.policy || !installed.receipt)
+        return { status: "disabled" };
+    if (installed.issues.length > 0)
+        return { status: "attention-required", issues: installed.issues };
+    const policy = installed.policy;
+    const duePath = path.join(locations.stateRoot, "due", `${digest(path.resolve(repository))}.json`);
+    const due = readJson(duePath);
+    const now = options.now ?? new Date();
+    if (due?.ranAt && now.getTime() - Date.parse(due.ranAt) < DAY_MS)
+        return { status: "not-due" };
+    const result = pruneBackups([repository], {
+        ...options,
+        depth: 0,
+        includeRegistry: false,
+        retentionDays: policy.retentionDays,
+        keepNewest: policy.keepNewest,
+        apply: !policy.dryRun,
+    });
+    atomicWrite(duePath, `${JSON.stringify({ schemaVersion: 1, ranAt: now.toISOString() })}\n`);
+    return { status: "ran", result };
+}
+export function formatBackupHuman(label, result) {
+    return `${label}\n${JSON.stringify(result, null, 2)}\n`;
+}