lovewebconnection 0.0.0-stage → 0.2.1

package/dist/plot.js

@@ -0,0 +1,317 @@
+import { existsSync, readFileSync } from "node:fs";
+export class PlotArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlotArgError";
+    }
+}
+export const DEFAULT_PLOT_WIDTH = 48;
+const MIN_PLOT_WIDTH = 10;
+const MAX_PLOT_WIDTH = 200;
+function parseWidth(raw) {
+    if (!/^\d+$/.test(raw)) {
+        throw new PlotArgError(`--width must be an integer between ${MIN_PLOT_WIDTH} and ${MAX_PLOT_WIDTH}.`);
+    }
+    const width = Number(raw);
+    if (width < MIN_PLOT_WIDTH || width > MAX_PLOT_WIDTH) {
+        throw new PlotArgError(`--width must be between ${MIN_PLOT_WIDTH} and ${MAX_PLOT_WIDTH}, got ${width}.`);
+    }
+    return width;
+}
+export function parsePlotArgs(argv) {
+    const positional = [];
+    let width = DEFAULT_PLOT_WIDTH;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--width") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new PlotArgError("--width requires a number.");
+            }
+            width = parseWidth(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--width=")) {
+            width = parseWidth(arg.slice("--width=".length));
+        }
+        else if (arg.startsWith("-")) {
+            continue; // --json and other global flags are handled by the CLI.
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const [path] = positional;
+    if (!path) {
+        throw new PlotArgError("A history CSV path is required: lwc plot ./balances.csv [--width 60]");
+    }
+    if (positional.length > 1) {
+        throw new PlotArgError(`Unexpected extra argument: ${positional[1]}.`);
+    }
+    return { path, width };
+}
+export function readHistoryCsv(path) {
+    if (!existsSync(path)) {
+        throw new PlotArgError(`history CSV not found: ${path}`);
+    }
+    return readFileSync(path, "utf8");
+}
+/**
+ * Minimal RFC 4180 reader: quoted cells may hold commas, newlines, and doubled
+ * quotes, which is exactly what the history CSV writes for labels and flags.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let cell = "";
+    let quoted = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const ch = text[index] ?? "";
+        if (quoted) {
+            if (ch === '"') {
+                if (text[index + 1] === '"') {
+                    cell += '"';
+                    index += 1;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else {
+                cell += ch;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            quoted = true;
+        }
+        else if (ch === ",") {
+            row.push(cell);
+            cell = "";
+        }
+        else if (ch === "\n") {
+            row.push(cell);
+            rows.push(row);
+            row = [];
+            cell = "";
+        }
+        else if (ch !== "\r") {
+            cell += ch;
+        }
+    }
+    if (cell !== "" || row.length > 0) {
+        row.push(cell);
+        rows.push(row);
+    }
+    return rows.filter((entry) => entry.length > 1 || (entry[0] ?? "") !== "");
+}
+/**
+ * Turn a history CSV into one point per portfolio sample. The long format
+ * repeats `usd_total` on every asset row of a sample, so rows are grouped by
+ * session and timestamp; when `usd_total` is empty, that sample's row-level
+ * `usd` values are summed instead so a partly priced portfolio still charts.
+ * The `--wide` pivot is read the same way, except its `usd_total` column is
+ * already one value per sample: `--wide`, `--wide --usd`, and `--wide
+ * --usd-only` all chart from it without summing asset columns.
+ */
+export function buildPlotReport(text, options) {
+    const width = options.width ?? DEFAULT_PLOT_WIDTH;
+    const rows = parseCsv(text);
+    const header = (rows[0] ?? []).map((cell) => cell.trim().toLowerCase());
+    const atIndex = header.indexOf("at");
+    const sessionIndex = header.indexOf("session");
+    const totalIndex = header.indexOf("usd_total");
+    const usdIndex = header.indexOf("usd");
+    if (atIndex === -1) {
+        throw new PlotArgError(`not a history CSV: ${options.path} has no at column (write it with history --csv).`);
+    }
+    if (totalIndex === -1 && usdIndex === -1) {
+        throw new PlotArgError(`no usd_total column in ${options.path}; write it with history --csv, long or --wide, from a watch --usd run.`);
+    }
+    const cell = (row, index) => index === -1 ? "" : (row[index] ?? "").trim();
+    const partials = new Map();
+    for (const row of rows.slice(1)) {
+        const atText = cell(row, atIndex);
+        if (atText === "")
+            continue;
+        const at = Date.parse(atText);
+        if (!Number.isFinite(at))
+            continue;
+        const session = cell(row, sessionIndex);
+        const key = `${session}\u0000${at}`;
+        let partial = partials.get(key);
+        if (partial === undefined) {
+            partial = { session, at, total: null, usdSum: 0, hasUsd: false };
+            partials.set(key, partial);
+        }
+        const totalText = cell(row, totalIndex);
+        if (totalText !== "" && Number.isFinite(Number(totalText))) {
+            partial.total = Number(totalText);
+        }
+        const usdText = cell(row, usdIndex);
+        if (usdText !== "" && Number.isFinite(Number(usdText))) {
+            partial.usdSum += Number(usdText);
+            partial.hasUsd = true;
+        }
+    }
+    const samples = [];
+    let skippedSamples = 0;
+    for (const partial of partials.values()) {
+        if (partial.total !== null) {
+            samples.push({ session: partial.session, at: partial.at, total: partial.total });
+        }
+        else if (partial.hasUsd) {
+            samples.push({
+                session: partial.session,
+                at: partial.at,
+                total: Math.round(partial.usdSum * 100) / 100,
+            });
+        }
+        else {
+            skippedSamples += 1;
+        }
+    }
+    samples.sort((a, b) => a.at - b.at || a.session.localeCompare(b.session));
+    const sessions = [];
+    for (const sample of samples) {
+        if (!sessions.includes(sample.session))
+            sessions.push(sample.session);
+    }
+    const totals = samples.map((sample) => sample.total);
+    const bounds = totals.length > 0 ? extent(totals) : null;
+    const first = samples[0]?.total ?? null;
+    const last = samples[samples.length - 1]?.total ?? null;
+    const change = first !== null && last !== null ? last - first : null;
+    const changePercent = change !== null && first !== null && first !== 0
+        ? (change / Math.abs(first)) * 100
+        : null;
+    return {
+        path: options.path,
+        width,
+        samples,
+        sessions,
+        skippedSamples,
+        firstAt: samples[0]?.at ?? null,
+        lastAt: samples[samples.length - 1]?.at ?? null,
+        first,
+        last,
+        min: bounds?.min ?? null,
+        max: bounds?.max ?? null,
+        change,
+        changePercent,
+        chart: sparkline(totals, width),
+    };
+}
+function extent(values) {
+    let min = values[0] ?? 0;
+    let max = min;
+    for (const value of values) {
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    return { min, max };
+}
+const SPARK_CHARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+const FLAT_CHAR = SPARK_CHARS[3] ?? "▄";
+/** Average a longer series into `width` buckets so the chart fits one line. */
+function resample(values, width) {
+    if (values.length <= width)
+        return values;
+    const buckets = [];
+    for (let index = 0; index < width; index += 1) {
+        const start = Math.floor((index * values.length) / width);
+        const end = Math.max(start + 1, Math.floor(((index + 1) * values.length) / width));
+        let sum = 0;
+        for (let cursor = start; cursor < end; cursor += 1) {
+            sum += values[cursor] ?? 0;
+        }
+        buckets.push(sum / (end - start));
+    }
+    return buckets;
+}
+/** One line of block characters: the smallest value is lowest, the largest is full. */
+export function sparkline(values, width = DEFAULT_PLOT_WIDTH) {
+    if (values.length === 0)
+        return "";
+    const points = resample(values, Math.max(1, width));
+    const { min, max } = extent(values);
+    if (max === min)
+        return FLAT_CHAR.repeat(points.length);
+    return points
+        .map((value) => {
+        const position = Math.round(((value - min) / (max - min)) * (SPARK_CHARS.length - 1));
+        const index = Math.max(0, Math.min(SPARK_CHARS.length - 1, position));
+        return SPARK_CHARS[index] ?? FLAT_CHAR;
+    })
+        .join("");
+}
+function formatUsd(value) {
+    return `$${value.toLocaleString("en-US", {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    })}`;
+}
+function signedUsd(value) {
+    return `${value >= 0 ? "+" : "-"}${formatUsd(Math.abs(value))}`;
+}
+function clockTime(at) {
+    return new Date(at).toISOString().slice(11, 19);
+}
+const LABEL_WIDTH = 12;
+function line(label, value) {
+    return `  ${label.padEnd(LABEL_WIDTH)}${value}`;
+}
+export function formatPlot(report) {
+    const lines = ["lwc — portfolio USD total", "", line("csv", report.path)];
+    if (report.samples.length === 0 ||
+        report.first === null ||
+        report.last === null ||
+        report.min === null ||
+        report.max === null ||
+        report.firstAt === null ||
+        report.lastAt === null) {
+        lines.push(line("samples", "0"));
+        if (report.skippedSamples > 0) {
+            lines.push(line("unpriced", `${report.skippedSamples} sample(s) skipped`));
+        }
+        lines.push("", "  no priced portfolio samples here (run watch with --usd)");
+        return lines.join("\n");
+    }
+    const percent = report.changePercent === null
+        ? "n/a"
+        : `${report.changePercent >= 0 ? "+" : ""}${report.changePercent.toFixed(2)}%`;
+    const change = report.change === null ? "n/a" : signedUsd(report.change);
+    lines.push(line("samples", `${report.samples.length}${report.sessions.length > 1 ? ` (${report.sessions.length} sessions)` : ""}`), line("window", `${new Date(report.firstAt).toISOString()} → ${new Date(report.lastAt).toISOString()}`), line("total", `${formatUsd(report.first)} → ${formatUsd(report.last)}  (${change}, ${percent})`), line("range", `${formatUsd(report.min)} – ${formatUsd(report.max)}`));
+    if (report.skippedSamples > 0) {
+        lines.push(line("unpriced", `${report.skippedSamples} sample(s) skipped`));
+    }
+    const maxLabel = formatUsd(report.max);
+    const minLabel = formatUsd(report.min);
+    const labelWidth = Math.max(maxLabel.length, minLabel.length);
+    lines.push("", `  ${maxLabel.padStart(labelWidth)} ┤${report.chart}`, `  ${minLabel.padStart(labelWidth)} ┤`, `  ${" ".repeat(labelWidth)} └─ ${clockTime(report.firstAt)} → ${clockTime(report.lastAt)} UTC`);
+    return lines.join("\n");
+}
+export function toPlotJson(report) {
+    return {
+        ok: true,
+        csv: report.path,
+        width: report.width,
+        sessions: report.sessions,
+        samples: report.samples.length,
+        skippedSamples: report.skippedSamples,
+        first: report.first,
+        last: report.last,
+        change: report.change,
+        changePercent: report.changePercent,
+        min: report.min,
+        max: report.max,
+        chart: report.chart,
+        series: report.samples.map((sample) => ({
+            session: sample.session,
+            at: new Date(sample.at).toISOString(),
+            usdTotal: sample.total,
+        })),
+    };
+}

package/dist/presets-history.d.ts

@@ -0,0 +1,372 @@
+import { toPresetsJson, type PresetsReport } from "./presets.ts";
+type PresetsJson = ReturnType<typeof toPresetsJson>;
+type PresetEndpoint = PresetsJson["endpoints"][number];
+/** One probe run, appended to a JSONL file. */
+export interface PresetHistoryRecord extends PresetsJson {
+    /** When the probe ran, ISO 8601. */
+    at: string;
+}
+export declare class PresetsHistoryArgError extends Error {
+    constructor(message: string);
+}
+/** The window `--since`, `--until` and `--limit` narrow a history file to. */
+export interface PresetsHistorySelection {
+    /** Epoch-ms cutoff: keep runs recorded at or after this time. */
+    since?: number | null;
+    /** Epoch-ms bound: keep runs recorded at or before this time. */
+    until?: number | null;
+    /** Keep only the newest N runs left inside the window. */
+    limit?: number | null;
+}
+/** What the file the runs came from says about itself. */
+export interface PresetsHistoryContext {
+    /** Retention declared by the file's header, or null when it declares none. */
+    retainMs?: number | null;
+}
+export interface PresetHistoryRow {
+    preset: string;
+    chainId: number;
+    nativeSymbol: string;
+    runs: number;
+    healthy: number;
+    failed: number;
+    /** Runs where the backup answered for this chain. */
+    failovers: number;
+    uptimePct: number;
+    p50LatencyMs: number | null;
+    maxLatencyMs: number | null;
+    lastAt: string | null;
+    lastFailureAt: string | null;
+}
+export interface PresetsHistorySummary {
+    /** Runs inside the window. */
+    runs: number;
+    /** Runs in the file before the window was applied. */
+    totalRuns: number;
+    from: string | null;
+    to: string | null;
+    /** The applied --since cutoff in epoch ms, or null. */
+    since: number | null;
+    /** The applied --until bound in epoch ms, or null. */
+    until: number | null;
+    /** The applied --limit, or null. */
+    limit: number | null;
+    healthyRuns: number;
+    failedRuns: number;
+    failoverRuns: number;
+    /** Oldest run in the file, before the window was applied. */
+    availableFrom: string | null;
+    /** Newest run in the file, before the window was applied. */
+    availableTo: string | null;
+    /** Retention the source file declares, or null when it declares none. */
+    retainMs: number | null;
+    presets: PresetHistoryRow[];
+}
+/** The earlier window `--compare <from>..<to>` reads as the "before" side. */
+export interface PresetsHistoryWindow {
+    /** Epoch-ms start, inclusive, reusing the --since syntax. */
+    since: number;
+    /** Epoch-ms end, inclusive, reusing the --until syntax. */
+    until: number;
+}
+/** One preset's uptime on each side of a comparison. */
+export interface PresetUptimeChange {
+    preset: string;
+    chainId: number;
+    nativeSymbol: string;
+    /** This preset in the earlier window, or null when it was not probed then. */
+    before: PresetHistoryRow | null;
+    /** This preset in the current window, or null when it was not probed now. */
+    after: PresetHistoryRow | null;
+    /** Percentage-point change (after − before), or null when a side is missing. */
+    deltaPct: number | null;
+}
+export interface PresetsHistoryComparison {
+    /** The earlier window, with the same shape as any other summary. */
+    before: PresetsHistorySummary;
+    /** The current window (`--since`/`--until`, no `--limit`). */
+    after: PresetsHistorySummary;
+    /** One row per preset seen on either side, worst regression first. */
+    presets: PresetUptimeChange[];
+    /** The same comparison pooled per provider host, worst regression first. */
+    providers: ProviderUptimeChange[];
+}
+/** One RPC provider across every preset that probes it in a window. */
+export interface ProviderHistoryRow {
+    /** Host of the primary endpoint: the provider being judged. */
+    host: string;
+    /** Preset probes attributed to this provider. */
+    probes: number;
+    /** Probes this provider's own endpoint answered. */
+    healthy: number;
+    /** Probes where it failed and a backup answered instead. */
+    failovers: number;
+    /** Probes where neither endpoint answered. */
+    failed: number;
+    /** Presets this provider serves in the window, sorted. */
+    presets: string[];
+    /** Share of probes the provider answered itself; a failover does not count. */
+    uptimePct: number;
+}
+/** One provider's uptime on each side of a comparison. */
+export interface ProviderUptimeChange {
+    /** Host of the primary endpoint, which identifies the provider. */
+    host: string;
+    /** This provider in the earlier window, or null when it was not probed then. */
+    before: ProviderHistoryRow | null;
+    /** This provider in the current window, or null when it is gone now. */
+    after: ProviderHistoryRow | null;
+    /** Percentage-point change (after − before), or null when a side is missing. */
+    deltaPct: number | null;
+}
+/** Append this run's report, creating the file and its directory if needed. */
+export declare function appendPresetHistory(path: string, report: PresetsReport, now?: Date): PresetHistoryRecord;
+/** A history file's runs plus the retention it was written with. */
+export interface PresetHistoryFile {
+    records: PresetHistoryRecord[];
+    /** Retention span declared in the file's header, or null when it has none. */
+    retainMs: number | null;
+}
+/**
+ * Read a history file, oldest first. A truncated or hand-edited line is skipped
+ * rather than losing every run that came before it. The first line may be a
+ * `lwc_history` header recording the retention the file was trimmed to, so a
+ * read that happens later can still explain which runs are simply gone.
+ */
+export declare function readPresetHistoryFile(path: string): PresetHistoryFile;
+/** The runs in a history file, oldest first; its retention header is ignored. */
+export declare function readPresetHistory(path: string): PresetHistoryRecord[];
+/** The union of several history files, with what the merge had to drop. */
+export interface PresetHistoryMerge {
+    /** Every run from every input, oldest first, duplicates removed. */
+    records: PresetHistoryRecord[];
+    /** Runs that appeared in more than one input. */
+    duplicates: number;
+    /** Runs each input contributed, in the order they were passed. */
+    counts: number[];
+    /** Runs dropped by the retention window. */
+    pruned: number;
+}
+/**
+ * Combine history files into one. The cache and the release asset each keep
+ * runs the other may have lost, so restore their union instead of whichever
+ * file happens to be longer. Identical runs are kept once, oldest first.
+ */
+/**
+ * Warns when a window being read starts before the runs retention kept.
+ *
+ * A trimmed history looks exactly like a provider that went quiet: the earlier
+ * side of a comparison has no runs for it, so its uptime is missing and no
+ * regression is reported. Naming the cutoff keeps that silence from being read
+ * as an outage.
+ */
+export declare function retentionWindowWarnings(newestAt: string | null, retainMs: number | null, windows: Array<{
+    label: string;
+    since: number | null;
+}>): string[];
+export declare function mergePresetHistory(inputs: PresetHistoryRecord[][], options?: {
+    retainMs?: number | null;
+}): PresetHistoryMerge;
+/**
+ * The tightest retention declared by the files being combined. A merge cannot
+ * hold runs that one input already pruned, so the union is bounded by the
+ * narrowest window rather than the widest.
+ */
+export declare function narrowestRetentionMs(values: Array<number | null>): number | null;
+/**
+ * Write a whole history file, replacing it, and create its directory. A
+ * retention window is recorded as the header readPresetHistoryFile returns, so
+ * the file itself says what it does not keep.
+ */
+export declare function savePresetHistory(path: string, records: PresetHistoryRecord[], options?: {
+    retainMs?: number | null;
+}): void;
+/**
+ * Apply --since/--until/--limit to a history, oldest first. A limit is only
+ * ever used to look at recent runs, so it keeps the tail.
+ */
+export declare function selectPresetHistory(records: PresetHistoryRecord[], selection?: PresetsHistorySelection): PresetHistoryRecord[];
+/**
+ * Attribute each probe to the host of the endpoint the preset is configured
+ * with, and pool those by provider: one host that serves several chains is
+ * judged once. A failover counts against the provider, because the backup
+ * answering is the same fact as the provider under test not answering.
+ */
+export declare function summarizeProviderHistory(records: PresetHistoryRecord[], selection?: PresetsHistorySelection): ProviderHistoryRow[];
+export declare function summarizePresetHistory(records: PresetHistoryRecord[], selection?: PresetsHistorySelection, context?: PresetsHistoryContext): PresetsHistorySummary;
+/** A preset whose uptime in the window sits below the --fail-under threshold. */
+export interface UptimeShortfall {
+    preset: string;
+    chainId: number;
+    uptimePct: number;
+    runs: number;
+    failed: number;
+}
+/** Presets below the threshold, worst first; empty when every preset clears it. */
+export declare function presetsBelowUptime(summary: PresetsHistorySummary, threshold: number): UptimeShortfall[];
+export interface PresetsGateReport {
+    /** False when any preset is below the threshold or the window is empty. */
+    passed: boolean;
+    threshold: number;
+    shortfalls: UptimeShortfall[];
+    /** The outcome as markdown for a CI run summary. */
+    markdown: string;
+}
+/**
+ * Judge a window against a minimum uptime for CI: markdown for the run summary
+ * plus the verdict the caller exits on. An empty window fails, because there is
+ * no run left that could clear the threshold.
+ */
+export declare function summarizePresetGate(summary: PresetsHistorySummary, threshold: number): PresetsGateReport;
+export declare function formatPresetHistory(summary: PresetsHistorySummary): string;
+/** One local pass over a history file: the gate plus what the file can cover. */
+export interface PresetsHistoryCheck {
+    /** The history file the report was made from. */
+    path: string;
+    /** Runs the gate judged. */
+    runs: number;
+    /** Presets judged in the window. */
+    presets: number;
+    /** The whole file's span and recorded count, before the window was applied. */
+    coverage: {
+        from: string | null;
+        to: string | null;
+        recorded: number;
+    };
+    /** The retention the file declares, or null when it declares none. */
+    retention: {
+        ms: number;
+        label: string;
+        cutoff: string;
+    } | null;
+    /** The freshness bound the gate applied, or null when it does not check age. */
+    maxAge: {
+        ms: number;
+        label: string;
+    } | null;
+    /** The newest run's age when it exceeds maxAge, or null when the file is fresh. */
+    stale: {
+        newest: string;
+        ageMs: number;
+        age: string;
+    } | null;
+    /** The filters the gate window applied. */
+    window: {
+        since: number | null;
+        until: number | null;
+        limit: number | null;
+    };
+    gate: {
+        threshold: number;
+        passed: boolean;
+        shortfalls: UptimeShortfall[];
+    };
+    /** Why the window may be missing runs retention pruned, or null. */
+    note: string | null;
+}
+/**
+ * Build the local check: the gate over the selected window plus the file's
+ * coverage and declared retention, so one command answers "did it pass, and
+ * what was it able to see?" without a CI run to assemble the pieces.
+ */
+export declare function presetHistoryCheck(path: string, summary: PresetsHistorySummary, threshold: number, options?: {
+    maxAgeMs?: number | null;
+    now?: number;
+}): PresetsHistoryCheck;
+/**
+ * One line per reason the check failed, in the order the report reads: a stale
+ * file first, then an empty window, then each preset below the threshold. The
+ * pre-commit hook prints these and CI annotates them, so both say the same
+ * thing without copying the wording.
+ */
+export declare function presetHistoryFailureReasons(check: PresetsHistoryCheck): string[];
+/**
+ * The newest runs with their age, as a markdown table for the CI summary. A
+ * verdict line cannot show that every row is old; a table can. The gate uses it
+ * only for a stale file, but the table reports either verdict so the wording
+ * lives in one tested place.
+ */
+export declare function presetFreshnessMarkdown(check: PresetsHistoryCheck, records: readonly PresetHistoryRecord[], options?: {
+    now?: number;
+    limit?: number;
+}): string | null;
+/**
+ * Render the local check as one aligned pass, ending in the verdict. Passing the
+ * records replaces the single stale line with the newest runs and their age, so
+ * a stopped schedule is visible row by row (five by default, or `rows`); without
+ * them the summary line stays.
+ */
+export declare function formatPresetHistoryCheck(check: PresetsHistoryCheck, records?: readonly PresetHistoryRecord[], options?: {
+    rows?: number;
+}): string;
+/**
+ * Judge a provider change by reading the same presets in two windows: the
+ * current one from the usual filters, and an explicit earlier one. Both sides
+ * are ordinary summaries, so a delta cannot disagree with either table.
+ */
+export declare function comparePresetHistory(records: PresetHistoryRecord[], selection: PresetsHistorySelection, compare: PresetsHistoryWindow, context?: PresetsHistoryContext): PresetsHistoryComparison;
+export declare function formatPresetHistoryComparison(comparison: PresetsHistoryComparison): string;
+/**
+ * Markdown for a CI run summary: the current window beside an earlier one, so
+ * a scheduled run reports the week-over-week delta without anyone asking.
+ */
+export declare function presetComparisonMarkdown(comparison: PresetsHistoryComparison, heading?: string): string;
+/**
+ * One line per preset whose uptime fell, worst first, for a CI annotation. A
+ * provider change that looks fine in this week's numbers still shows up here if
+ * it made any preset worse than the week it replaced.
+ */
+export declare function presetRegressionWarnings(comparison: PresetsHistoryComparison): string[];
+/**
+ * One line per provider host whose uptime fell, worst first. The same week can
+ * regress several presets for one reason; this names the upstream once, so the
+ * run log says which provider got worse rather than only which chains did.
+ */
+export declare function providerRegressionWarnings(comparison: PresetsHistoryComparison): string[];
+export declare function toPresetHistoryJson(summary: PresetsHistorySummary): PresetsHistorySummary;
+/** One CSV row per preset in the window, for charting uptime and latency. */
+export declare function presetHistoryCsv(summary: PresetsHistorySummary): string;
+/** Write the CSV to a file, creating its directory. */
+export declare function savePresetHistoryCsv(path: string, csv: string): void;
+/**
+ * One CSV row per preset per run, oldest first, for charting health over time
+ * rather than summarizing it: a failure keeps its latency and via cells blank.
+ */
+export declare function presetHistoryTimelineCsv(records: PresetHistoryRecord[], selection?: PresetsHistorySelection): string;
+export interface PresetsHistoryArgs {
+    path: string;
+    /** Epoch-ms cutoff from --since, or null for the whole file. */
+    since: number | null;
+    /** Epoch-ms bound from --until, or null to keep everything after --since. */
+    until: number | null;
+    /** Newest N runs to keep, or null for all of them. */
+    limit: number | null;
+    /** Exit non-zero below this uptime percentage, or null to only report. */
+    failUnder: number | null;
+    /** Where to write the per-preset CSV, "-" for stdout, or null for the table. */
+    csvPath: string | null;
+    /** Where to write the per-run timeline CSV, "-" for stdout, or null. */
+    timelinePath: string | null;
+    /** The earlier window from --compare, or null to report one window. */
+    compare: PresetsHistoryWindow | null;
+    /** Extra history files from --merge, folded into `path` before anything reads it. */
+    merge: string[];
+    /** Where --out writes the merged history, or null to only read it. */
+    out: string | null;
+    /** Epoch-ms retention window for the merge from --retain, or null to keep everything. */
+    retain: number | null;
+    /** Epoch-ms freshness bound from --max-age, or null to judge the gate on uptime alone. */
+    maxAge: number | null;
+    /** Rows the stale report prints from --freshness-rows, or null for the default. */
+    freshnessRows: number | null;
+    /** Report the file's coverage and retention beside the gate in one local pass. */
+    check: boolean;
+}
+export declare function parsePresetHistoryArgs(argv: string[], now?: number): PresetsHistoryArgs;
+/** A retention window as a positive span (`180d`), for --retain and the CI merge. */
+export declare function parseRetentionMs(raw: string): number;
+/** A freshness row count as a positive whole number (`5`), for --freshness-rows. */
+export declare function parseFreshnessRows(raw: string): number;
+/** A freshness bound as a positive span (`7d`), for --max-age. */
+export declare function parseMaxAgeMs(raw: string): number;
+export type { PresetsReport, PresetEndpoint };