n8n-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flow-84
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# n8n-guard
+
+[![npm](https://img.shields.io/npm/v/n8n-guard.svg)](https://www.npmjs.com/package/n8n-guard)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.flow--84%2Fn8n--guard-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=n8n-guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+
+An MCP server for the operational layer *underneath* the n8n Public API.
+
+Every n8n MCP server on the registry today is a wrapper around the same public
+endpoints: list workflows, list executions, create, activate, delete. That is
+useful for building workflows. It is close to useless for keeping a self-hosted
+instance alive, because the things that actually take an instance down are not
+in that API at all.
+
+n8n-guard answers the four questions the API cannot:
+
+1. **How big is the datastore, and when does it become a problem?** The Public
+   API has no endpoint for database size. n8n-guard reads the SQLite file or
+   queries Postgres directly, breaks the size down per table, derives the growth
+   rate, and tells you how many days of headroom are left.
+2. **Which executions are stuck?** Listing executions by status is not
+   detection. A run sitting in `running` looks identical to a healthy long job
+   until you compare it against what that workflow normally takes. n8n-guard
+   builds a per-workflow median from finished runs and flags the outliers.
+3. **What is retention costing?** How many execution records are stored, how far
+   back they reach, and what a given retention window would free.
+4. **Has the instance drifted from git?** Existing servers diff one API object
+   against another. n8n-guard diffs the running instance against the JSON
+   exports in a repository: live but never exported, exported but deleted,
+   and content that quietly diverged.
+
+It is strictly read-only. n8n-guard never writes to your instance, never deletes
+executions, and never activates or edits a workflow. It reports; you decide.
+
+## Install
+
+```bash
+npx -y n8n-guard
+```
+
+Requires Node.js 22 or newer (it uses the built-in `node:sqlite`). For a
+permanent install use `npm install -g n8n-guard`.
+
+### Claude Desktop / any MCP client
+
+```json
+{
+  "mcpServers": {
+    "n8n-guard": {
+      "command": "n8n-guard",
+      "env": {
+        "N8N_URL": "https://n8n.example.com",
+        "N8N_API_KEY": "n8n_api_...",
+        "N8N_SQLITE_PATH": "/var/lib/n8n/.n8n/database.sqlite",
+        "N8N_GIT_REPO_PATH": "/srv/workflow-exports"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Everything is an environment variable. There are no hardcoded hosts, paths,
+container names or accounts, so the server runs against any self-hosted
+instance.
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `N8N_URL` | no | `http://localhost:5678` | Base URL of the instance |
+| `N8N_API_KEY` | for execution and workflow checks | none | Public API key (Settings, n8n API) |
+| `N8N_SQLITE_PATH` | for datastore checks on SQLite | none | Path to `database.sqlite` |
+| `N8N_POSTGRES_URL` | for datastore checks on Postgres | none | Connection string, takes precedence over SQLite |
+| `N8N_GIT_REPO_PATH` | for the drift check | none | Checkout holding exported workflow JSON |
+| `N8N_GUARD_STUCK_MINUTES` | no | `15` | Minutes in `running` before a run counts as stuck |
+| `N8N_GUARD_DB_WARN_BYTES` | no | `1073741824` (1 GB) | Datastore warning threshold |
+| `N8N_GUARD_DB_CRITICAL_BYTES` | no | `4294967296` (4 GB) | Datastore critical threshold |
+| `N8N_GUARD_TIMEOUT_MS` | no | `15000` | Per-request API timeout |
+
+Partial configuration is a supported mode, not an error. With only `N8N_URL` and
+`N8N_SQLITE_PATH` you still get disk and retention answers; the API-backed checks
+report that they are unconfigured and the rest of the run continues.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `instance_info` | Reachability, configured datastore, workflow inventory. Shows which checks are usable. |
+| `db_health` | Datastore size, per-table breakdown, growth rate, projected days until the critical threshold. |
+| `stuck_executions` | Runs stuck in `running`, judged against the absolute threshold and each workflow's own median. |
+| `retention_report` | Execution count, age span, and what pruning to a retention window would free. |
+| `git_drift` | Live workflows against the repository exports: missing, deleted, drifted, duplicated. |
+| `guard_run` | All of the above in one resilient sweep. This is the one to schedule. |
+
+## Example call
+
+Point the server at an instance and let your client call a tool. Every tool
+answers with a readable summary first and the full structured payload after it:
+
+```
+## Retention report
+- 200 execution records spanning 8.3 days (24.1/day)
+- nothing older than 30 days, retention is already tight
+- n8n-guard never deletes. To act on this, set EXECUTIONS_DATA_PRUNE=true and
+  EXECUTIONS_DATA_MAX_AGE=720 (hours) on the n8n instance, then restart it.
+```
+
+followed by the structured payload the summary was derived from:
+
+```json
+{
+  "executionCount": 200,
+  "oldestExecutionAt": "2026-08-28T23:43:28.651Z",
+  "spanDays": 8.29,
+  "executionsPerDay": 24.12,
+  "buckets": [
+    { "olderThanDays": 7, "rows": 32, "share": 0.16, "estimatedBytes": 3277 },
+    { "olderThanDays": 30, "rows": 0, "share": 0, "estimatedBytes": 0 }
+  ]
+}
+```
+
+`guard_run` wraps all six checks. With only a datastore configured it reports
+the gap instead of aborting:
+
+```
+## Guard run (degraded)
+- stuck_executions failed after 3 attempt(s): N8N_API_KEY is not set, so the n8n Public API cannot be queried
+- git_drift failed after 2 attempt(s): N8N_GIT_REPO_PATH is not set, so there is nothing to diff the instance against
+- 4 of 6 checks completed despite the failures above
+```
+
+## Recovery: `guard_run` survives a partial outage
+
+A monitoring run that aborts on the first unreachable dependency is worthless
+precisely when it matters. The API being down *is* the incident, and it is no
+reason to stop looking at the disk.
+
+`guard_run` isolates every step. A failing step is retried with backoff, and if
+it still fails it becomes a finding while the remaining checks run to completion.
+Steps that depend on a failed step are skipped with the reason attached rather
+than crashing on missing input. The report says so plainly:
+
+```
+## Guard run (degraded)
+- stuck_executions failed after 3 attempt(s): cannot reach http://n8n.internal:5678: fetch failed
+- git_drift skipped: depends on instance, which failed
+- 4 of 6 checks completed despite the failures above
+```
+
+This behaviour is covered by tests in `test/unit/runner.test.ts` and
+`test/unit/serviceRecovery.test.ts`, the latter running a real SQLite datastore
+against a deliberately dead API endpoint.
+
+## Try it on a throwaway instance
+
+The compose file starts a fresh n8n you can safely point the server at. The data
+directory is bind-mounted, which is exactly how n8n-guard reads a real
+deployment.
+
+```bash
+git clone https://github.com/flow-84/n8n-guard && cd n8n-guard
+npm install && npm run build
+
+docker compose up -d
+./scripts/demo-setup.sh     # owner, API key, workflows, and a drifted export folder
+```
+
+The script generates the owner password, keeps it in the gitignored
+`.n8n-demo-credentials`, and prints it along with the environment block to run
+the server with. It seeds one
+workflow that matches its export, one that was never exported, and one export
+whose workflow does not exist, so `git_drift` has something real to find.
+
+```bash
+export N8N_URL=http://localhost:5678
+export N8N_API_KEY=...            # printed by the script
+export N8N_SQLITE_PATH=$PWD/.n8n-demo/database.sqlite
+export N8N_GIT_REPO_PATH=$PWD/.n8n-demo-exports
+npm start
+```
+
+Use `N8N_DEMO_PORT=5679 docker compose up -d` if port 5678 is already taken by
+an instance you care about.
+
+## Tests
+
+```bash
+npm test              # unit tests, no instance required
+npm run test:integration   # against the compose instance above
+```
+
+The integration suite skips the API-backed cases when `N8N_API_KEY` is unset, so
+it stays runnable on a bare `docker compose up`.
+
+## License
+
+MIT

package/dist/checks/dbHealth.d.ts

@@ -0,0 +1,36 @@
+import type { DatastoreStats } from "../n8n/datastore.js";
+export type Severity = "ok" | "warning" | "critical";
+export interface DbHealthThresholds {
+    warnBytes: number;
+    criticalBytes: number;
+}
+export interface DbHealthReport {
+    kind: DatastoreStats["kind"];
+    totalBytes: number;
+    totalHuman: string;
+    severity: Severity;
+    components: {
+        name: string;
+        bytes: number;
+    }[];
+    tables: {
+        table: string;
+        rows: number;
+        bytes: number | null;
+        share: number | null;
+    }[];
+    /** Average bytes added per day, derived from the age of the oldest execution. */
+    growthBytesPerDay: number | null;
+    /** Days until the datastore reaches `criticalBytes` at the observed growth rate. */
+    daysUntilCritical: number | null;
+    /** Bytes stored per execution record; the lever that retention pruning pulls on. */
+    bytesPerExecution: number | null;
+    findings: string[];
+}
+export declare function humanBytes(bytes: number): string;
+/**
+ * Pure assessment of a datastore snapshot. The n8n Public API exposes none of
+ * this: it has no endpoint for database size, so an API wrapper cannot warn
+ * before the disk fills up and the instance stops accepting executions.
+ */
+export declare function assessDatabaseHealth(stats: DatastoreStats, thresholds: DbHealthThresholds, now?: number): DbHealthReport;

package/dist/checks/dbHealth.js

@@ -0,0 +1,69 @@
+export function humanBytes(bytes) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let value = Math.abs(bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const sign = bytes < 0 ? "-" : "";
+    return `${sign}${value.toFixed(value >= 100 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+/**
+ * Pure assessment of a datastore snapshot. The n8n Public API exposes none of
+ * this: it has no endpoint for database size, so an API wrapper cannot warn
+ * before the disk fills up and the instance stops accepting executions.
+ */
+export function assessDatabaseHealth(stats, thresholds, now = Date.now()) {
+    const findings = [];
+    let severity = "ok";
+    if (stats.totalBytes >= thresholds.criticalBytes)
+        severity = "critical";
+    else if (stats.totalBytes >= thresholds.warnBytes)
+        severity = "warning";
+    if (severity !== "ok") {
+        findings.push(`datastore is ${humanBytes(stats.totalBytes)}, at or past the ${severity} threshold of ` +
+            `${humanBytes(severity === "critical" ? thresholds.criticalBytes : thresholds.warnBytes)}`);
+    }
+    const oldest = stats.oldestExecutionAt ? Date.parse(stats.oldestExecutionAt) : NaN;
+    const ageDays = Number.isNaN(oldest) ? null : Math.max((now - oldest) / 86_400_000, 1 / 24);
+    const growthBytesPerDay = ageDays === null ? null : stats.totalBytes / ageDays;
+    let daysUntilCritical = null;
+    if (growthBytesPerDay !== null && growthBytesPerDay > 0) {
+        const headroom = thresholds.criticalBytes - stats.totalBytes;
+        daysUntilCritical = headroom <= 0 ? 0 : headroom / growthBytesPerDay;
+        if (daysUntilCritical <= 30) {
+            findings.push(`at ${humanBytes(growthBytesPerDay)}/day the datastore reaches ` +
+                `${humanBytes(thresholds.criticalBytes)} in about ${daysUntilCritical.toFixed(1)} days`);
+            if (severity === "ok")
+                severity = "warning";
+        }
+    }
+    const bytesPerExecution = stats.executionCount > 0 ? stats.totalBytes / stats.executionCount : null;
+    const tables = stats.tables
+        .map((t) => ({ ...t, share: t.bytes !== null && stats.totalBytes > 0 ? t.bytes / stats.totalBytes : null }))
+        .sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0) || b.rows - a.rows);
+    const dominant = tables.find((t) => t.share !== null && t.share >= 0.5);
+    if (dominant) {
+        findings.push(`${dominant.table} holds ${(dominant.share * 100).toFixed(0)}% of the datastore`);
+    }
+    if (stats.kind === "sqlite" && tables.every((t) => t.bytes === null)) {
+        findings.push("per-table sizes unavailable: this SQLite build lacks the dbstat module, row counts only");
+    }
+    if (findings.length === 0) {
+        findings.push(`datastore is ${humanBytes(stats.totalBytes)} and below all thresholds`);
+    }
+    return {
+        kind: stats.kind,
+        totalBytes: stats.totalBytes,
+        totalHuman: humanBytes(stats.totalBytes),
+        severity,
+        components: stats.components,
+        tables,
+        growthBytesPerDay,
+        daysUntilCritical,
+        bytesPerExecution,
+        findings,
+    };
+}
+//# sourceMappingURL=dbHealth.js.map

package/dist/checks/dbHealth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbHealth.js","sourceRoot":"","sources":["../../src/checks/dbHealth.ts"],"names":[],"mappings":"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"}

package/dist/checks/gitDrift.d.ts

@@ -0,0 +1,41 @@
+import type { N8nWorkflow } from "../n8n/api.js";
+export interface ExportedWorkflow {
+    id: string | null;
+    name: string;
+    nodes?: unknown[];
+    connections?: Record<string, unknown>;
+    /** Repo-relative path of the file this was read from. */
+    file: string;
+}
+export type DriftKind = "missing_in_git" | "missing_in_instance" | "content_drift" | "duplicate_export";
+export interface DriftEntry {
+    kind: DriftKind;
+    workflowId: string | null;
+    name: string;
+    file: string | null;
+    active: boolean | null;
+    detail: string;
+}
+export interface GitDriftReport {
+    liveCount: number;
+    exportedCount: number;
+    inSync: number;
+    drift: DriftEntry[];
+    findings: string[];
+}
+/**
+ * Fingerprint of what a workflow *does*: node types, their parameters and the
+ * wiring. Canvas positions, timestamps and per-instance ids are excluded, so a
+ * dragged node is not reported as drift.
+ */
+export declare function fingerprintWorkflow(workflow: {
+    nodes?: unknown[];
+    connections?: unknown;
+}): string;
+/**
+ * The diff every existing n8n MCP server is missing: it compares two API
+ * objects, not the running instance against what is versioned in git.
+ */
+export declare function diffWorkflows(live: N8nWorkflow[], exported: ExportedWorkflow[]): GitDriftReport;
+/** Reads every workflow-shaped JSON file under `repoPath`, recursively. */
+export declare function loadExportedWorkflows(repoPath: string): Promise<ExportedWorkflow[]>;

package/dist/checks/gitDrift.js

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Fingerprint of what a workflow *does*: node types, their parameters and the
+ * wiring. Canvas positions, timestamps and per-instance ids are excluded, so a
+ * dragged node is not reported as drift.
+ */
+export function fingerprintWorkflow(workflow) {
+    const nodes = Array.isArray(workflow.nodes) ? workflow.nodes : [];
+    const normalizedNodes = nodes
+        .map((raw) => {
+        const node = (raw ?? {});
+        return {
+            name: node.name ?? null,
+            type: node.type ?? null,
+            typeVersion: node.typeVersion ?? null,
+            disabled: node.disabled ?? false,
+            parameters: node.parameters ?? {},
+        };
+    })
+        .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    return createHash("sha256")
+        .update(stableStringify({ nodes: normalizedNodes, connections: workflow.connections ?? {} }))
+        .digest("hex");
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/**
+ * The diff every existing n8n MCP server is missing: it compares two API
+ * objects, not the running instance against what is versioned in git.
+ */
+export function diffWorkflows(live, exported) {
+    const available = new Set(exported);
+    const claimed = new Map();
+    const pick = (predicate) => {
+        for (const item of available)
+            if (predicate(item))
+                return item;
+        return undefined;
+    };
+    // Two passes, because an export may only be claimed once. Duplicating a
+    // workflow in n8n keeps the name, so same-name pairs are the normal case:
+    // matching by name first would let one of them consume the export another
+    // workflow owns by id, and the unexported twin would silently look in sync.
+    const assignment = new Map();
+    for (const workflow of live) {
+        const match = pick((item) => item.id !== null && item.id === String(workflow.id));
+        if (match) {
+            available.delete(match);
+            claimed.set(match, workflow);
+            assignment.set(workflow, match);
+        }
+    }
+    for (const workflow of live) {
+        if (assignment.has(workflow))
+            continue;
+        const match = pick((item) => item.name === workflow.name);
+        if (match) {
+            available.delete(match);
+            claimed.set(match, workflow);
+            assignment.set(workflow, match);
+        }
+    }
+    const drift = [];
+    let inSync = 0;
+    for (const workflow of live) {
+        const match = assignment.get(workflow);
+        if (!match) {
+            drift.push({
+                kind: "missing_in_git",
+                workflowId: String(workflow.id),
+                name: workflow.name,
+                file: null,
+                active: workflow.active,
+                detail: workflow.active
+                    ? "active in the instance but not exported to the repository"
+                    : "present in the instance but not exported to the repository",
+            });
+            continue;
+        }
+        if (fingerprintWorkflow(workflow) === fingerprintWorkflow(match)) {
+            inSync += 1;
+        }
+        else {
+            drift.push({
+                kind: "content_drift",
+                workflowId: String(workflow.id),
+                name: workflow.name,
+                file: match.file,
+                active: workflow.active,
+                detail: `nodes or connections differ between the instance and ${match.file}`,
+            });
+        }
+    }
+    // Whatever is left over was claimed by nobody. If a live workflow already
+    // took an export with the same identity, the leftovers are redundant copies
+    // of it; otherwise the workflow they describe is gone from the instance.
+    const identities = new Map();
+    for (const [item, workflow] of claimed) {
+        if (item.id)
+            identities.set(`id:${item.id}`, workflow);
+        identities.set(`name:${item.name}`, workflow);
+    }
+    for (const item of available) {
+        const owner = (item.id ? identities.get(`id:${item.id}`) : undefined) ?? identities.get(`name:${item.name}`);
+        if (owner) {
+            drift.push({
+                kind: "duplicate_export",
+                workflowId: String(owner.id),
+                name: owner.name,
+                file: item.file,
+                active: owner.active,
+                detail: `a second export file claims this workflow, alongside ${assignment.get(owner).file}`,
+            });
+            continue;
+        }
+        drift.push({
+            kind: "missing_in_instance",
+            workflowId: item.id,
+            name: item.name,
+            file: item.file,
+            active: null,
+            detail: "exported in the repository but not present in the instance (deleted or never imported)",
+        });
+    }
+    const counts = drift.reduce((acc, entry) => {
+        acc[entry.kind] = (acc[entry.kind] ?? 0) + 1;
+        return acc;
+    }, {});
+    const findings = drift.length === 0
+        ? [`all ${live.length} workflows match their exports`]
+        : [
+            `${drift.length} differences across ${live.length} live and ${exported.length} exported workflows`,
+            ...Object.entries(counts).map(([kind, n]) => `${kind}: ${n}`),
+        ];
+    return { liveCount: live.length, exportedCount: exported.length, inSync, drift, findings };
+}
+const SKIP_DIRS = new Set([".git", "node_modules", ".github", "dist", "build"]);
+/** Reads every workflow-shaped JSON file under `repoPath`, recursively. */
+export async function loadExportedWorkflows(repoPath) {
+    const root = path.resolve(repoPath);
+    const info = await stat(root).catch(() => null);
+    if (!info?.isDirectory()) {
+        throw new Error(`N8N_GIT_REPO_PATH is not a readable directory: ${repoPath}`);
+    }
+    const found = [];
+    const walk = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    await walk(full);
+                continue;
+            }
+            if (!entry.name.endsWith(".json"))
+                continue;
+            const parsed = await readFile(full, "utf8").then((text) => JSON.parse(text)).catch(() => null);
+            for (const candidate of Array.isArray(parsed) ? parsed : [parsed]) {
+                const workflow = toExported(candidate, path.relative(root, full));
+                if (workflow)
+                    found.push(workflow);
+            }
+        }
+    };
+    await walk(root);
+    return found;
+}
+function toExported(value, file) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    // A workflow export always carries nodes; package.json and friends do not.
+    if (!Array.isArray(record.nodes))
+        return null;
+    return {
+        id: record.id === undefined || record.id === null ? null : String(record.id),
+        name: typeof record.name === "string" ? record.name : path.basename(file, ".json"),
+        nodes: record.nodes,
+        connections: (record.connections ?? {}),
+        file,
+    };
+}
+//# sourceMappingURL=gitDrift.js.map

package/dist/checks/gitDrift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitDrift.js","sourceRoot":"","sources":["../../src/checks/gitDrift.ts"],"names":[],"mappings":"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"}

package/dist/checks/retention.d.ts

@@ -0,0 +1,29 @@
+import type { DatastoreStats } from "../n8n/datastore.js";
+export interface RetentionReport {
+    executionCount: number;
+    oldestExecutionAt: string | null;
+    newestExecutionAt: string | null;
+    spanDays: number | null;
+    executionsPerDay: number | null;
+    buckets: {
+        olderThanDays: number;
+        rows: number;
+        share: number;
+        estimatedBytes: number | null;
+    }[];
+    recommendation: {
+        keepDays: number;
+        prunableRows: number;
+        estimatedBytesFreed: number | null;
+        estimatedHumanFreed: string | null;
+    } | null;
+    findings: string[];
+    /** n8n prunes on its own only when these are set; guard reports, it never writes. */
+    hint: string;
+}
+/**
+ * Turns raw execution counts into "what does deleting old runs actually buy me".
+ * Byte figures are estimates: they assume execution rows cost the same on
+ * average, which is what the row-count-to-size ratio can support.
+ */
+export declare function analyzeRetention(stats: DatastoreStats, keepDays?: number, now?: number): RetentionReport;