freeharness 0.4.1 → 0.4.2

package/dist/cli/cost-quota.js

@@ -0,0 +1,645 @@
+// `freeharness cost quota`: no official per-token quota weight exists, so the window percentages
+// the quota tap records are fitted against the tokens the transcripts recorded between two
+// readings. Reads the readings and transcripts under the user's ~/.claude; writes only
+// quota-calibration.json, and only with --write. index.ts prints.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { familyOf } from "./cost.js";
+export const QUOTA_WINDOWS = ["five_hour", "seven_day"];
+/** Same order as cost.ts's family list, so weights print in the routing report's order. */
+const FAMILY_ORDER = ["opus", "sonnet", "haiku", "fable", "other"];
+export const DEFAULT_QUOTA_DAYS = 14;
+const DAY_MS = 24 * 3600 * 1000;
+/** The tap rotates past 2 MiB; anything far larger is not its file. */
+const MAX_READINGS_BYTES = 16 * 1024 * 1024;
+/** The cost tracker's per-file transcript bounds (main and subagent), so both skip the same files. */
+const MAX_MAIN_TRANSCRIPT_BYTES = 256 * 1024 * 1024;
+const MAX_SUBAGENT_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+const MAX_CALIBRATION_BYTES = 1024 * 1024;
+const MAX_MODEL_CHARS = 128;
+const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u;
+/** Fewer rows than this per fitted weight leaves a least-squares fit too loose to trust. */
+const INTERVALS_PER_FEATURE = 3;
+const NOTE = "note: usage on the same account outside Claude Code (claude.ai, other machines) is invisible to these transcripts and inflates the weights";
+export function quotaDir(home = os.homedir()) {
+    return path.join(home, ".claude", "freeharness");
+}
+export function quotaCalibrationPath(home = os.homedir()) {
+    return path.join(quotaDir(home), "quota-calibration.json");
+}
+/** Strips float noise so a re-run over the same inputs prints and stores the same numbers. */
+function clean(x) {
+    const r = Math.round(x * 1e9) / 1e9;
+    return r === 0 ? 0 : r;
+}
+function own(obj, key) {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj))
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * A file's text through one descriptor that never follows a symlink leaf or blocks on a FIFO.
+ * @returns The text, or the reason it was not read.
+ */
+function readBounded(file, maxBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK || 0));
+    }
+    catch (e) {
+        const code = e.code;
+        return { text: null, reason: code === "ENOENT" ? "absent" : code === "ELOOP" ? "irregular" : "unreadable" };
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return { text: null, reason: "irregular" };
+        if (st.size > maxBytes)
+            return { text: null, reason: "oversize" };
+        const buf = Buffer.allocUnsafe(st.size);
+        let total = 0;
+        while (total < buf.length) {
+            const n = fs.readSync(fd, buf, total, buf.length - total, total);
+            if (n === 0)
+                break;
+            total += n;
+        }
+        return { text: buf.toString("utf8", 0, total), reason: null };
+    }
+    catch {
+        return { text: null, reason: "unreadable" };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The tap's window rule, so a line the tap would never write counts as malformed. */
+function windowOf(value) {
+    if (value === null)
+        return null;
+    const pct = own(value, "used_percentage");
+    const resets = own(value, "resets_at");
+    if (typeof pct !== "number" || !Number.isFinite(pct) || pct < 0 || pct > 100)
+        return undefined;
+    if (typeof resets !== "number" || !Number.isSafeInteger(resets) || resets <= 0)
+        return undefined;
+    return { used_percentage: pct, resets_at: resets };
+}
+/** A readings line in the sink schema, else null (malformed). */
+export function parseReading(raw) {
+    let rec;
+    try {
+        rec = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(rec))
+        return null;
+    const ts = own(rec, "ts");
+    const time = typeof ts === "string" ? Date.parse(ts) : NaN;
+    if (!Number.isFinite(time))
+        return null;
+    const five = windowOf(own(rec, "five_hour") ?? null);
+    const seven = windowOf(own(rec, "seven_day") ?? null);
+    if (five === undefined || seven === undefined || (five === null && seven === null))
+        return null;
+    const m = own(rec, "model");
+    const model = typeof m === "string" && m.length > 0 && m.length <= MAX_MODEL_CHARS && !UNSAFE_CHARS.test(m) ? m : null;
+    return { ts: new Date(time).toISOString(), time, model, five_hour: five, seven_day: seven };
+}
+/** Readings from the rotation then the live file, within the last `days`, in time order. */
+export function readReadings(home, days, now) {
+    const dir = quotaDir(home);
+    const since = now.getTime() - days * DAY_MS;
+    const report = { files: [], lines: 0, malformed: 0, out_of_range: 0, skipped: [] };
+    const readings = [];
+    for (const name of ["quota-readings.jsonl.1", "quota-readings.jsonl"]) {
+        const file = path.join(dir, name);
+        const { text, reason } = readBounded(file, MAX_READINGS_BYTES);
+        if (text === null) {
+            if (reason !== "absent")
+                report.skipped.push(`${name} (${reason === "oversize" ? "over the size bound" : reason === "irregular" ? "a symlink or not a regular file" : "unreadable"})`);
+            continue;
+        }
+        report.files.push(file);
+        for (const raw of text.split("\n")) {
+            if (!raw.trim())
+                continue;
+            const r = parseReading(raw);
+            if (r === null)
+                report.malformed += 1;
+            else if (r.time < since)
+                report.out_of_range += 1;
+            else {
+                report.lines += 1;
+                readings.push(r);
+            }
+        }
+    }
+    // Stable: equal times keep file order, the order the tap appended them in.
+    readings.sort((a, b) => a.time - b.time);
+    return { readings, report };
+}
+/**
+ * Rising intervals per window. A reading repeating the window's previous percentage and reset is
+ * no new reading for that window (the other window changed), so the interval starts at the first
+ * reading of the value and keeps the tokens spent while the meter had not yet moved.
+ */
+export function formIntervals(readings) {
+    const out = { five_hour: [], seven_day: [] };
+    for (const window of QUOTA_WINDOWS) {
+        const seen = new Set();
+        let prev = null;
+        for (const r of readings) {
+            const cur = r[window];
+            if (cur === null)
+                continue;
+            const p = prev ? prev[window] : null;
+            if (prev && p && p.resets_at === cur.resets_at && p.used_percentage === cur.used_percentage)
+                continue;
+            if (prev && p && p.resets_at === cur.resets_at && cur.used_percentage > p.used_percentage) {
+                const key = `${window}|${cur.resets_at}|${prev.time}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out[window].push({
+                        window,
+                        resets_at: cur.resets_at,
+                        delta: clean(cur.used_percentage - p.used_percentage),
+                        start: { ts: prev.ts, model: prev.model, used_percentage: p.used_percentage },
+                        end: { ts: r.ts, model: r.model, used_percentage: cur.used_percentage },
+                    });
+                }
+            }
+            prev = r;
+        }
+    }
+    return out;
+}
+function count(v) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/** Main transcripts and their `subagents/agent-*.jsonl`, the layout the cost tracker reads; symlinks are never followed. */
+function transcriptFiles(home) {
+    const root = path.join(home, ".claude", "projects");
+    const out = [];
+    const dirents = (dir) => {
+        try {
+            return fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+    };
+    for (const project of dirents(root)) {
+        if (!project.isDirectory())
+            continue;
+        const pdir = path.join(root, project.name);
+        for (const e of dirents(pdir)) {
+            if (e.isFile() && e.name.endsWith(".jsonl"))
+                out.push({ file: path.join(pdir, e.name), max: MAX_MAIN_TRANSCRIPT_BYTES });
+            if (!e.isDirectory())
+                continue;
+            for (const s of dirents(path.join(pdir, e.name, "subagents"))) {
+                if (s.isFile() && /^agent-.+\.jsonl$/.test(s.name))
+                    out.push({ file: path.join(pdir, e.name, "subagents", s.name), max: MAX_SUBAGENT_TRANSCRIPT_BYTES });
+            }
+        }
+    }
+    return out.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+}
+/**
+ * Assistant messages with usage, one per `message.id` (else per file and line); the last line of
+ * an id wins, as in the cost tracker, since a streamed message repeats its usage on every line.
+ * A file last written before `since` cannot hold a message inside any interval and is not read.
+ */
+export function readMessages(home, since) {
+    const report = { files: 0, oversize: 0, skipped: 0, messages: 0 };
+    const byId = new Map();
+    for (const { file, max } of transcriptFiles(home)) {
+        let st;
+        try {
+            st = fs.lstatSync(file);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile()) {
+            report.skipped += 1;
+            continue;
+        }
+        if (st.size > max) {
+            report.oversize += 1;
+            continue;
+        }
+        if (st.mtimeMs < since)
+            continue;
+        const { text, reason } = readBounded(file, max);
+        if (text === null) {
+            if (reason === "oversize")
+                report.oversize += 1;
+            else
+                report.skipped += 1;
+            continue;
+        }
+        report.files += 1;
+        const lines = text.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const raw = lines[i];
+            if (!raw.includes('"assistant"') || !raw.includes('"usage"'))
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (own(rec, "type") !== "assistant")
+                continue;
+            const msg = own(rec, "message");
+            const usage = own(msg, "usage");
+            if (!isPlainObject(usage))
+                continue;
+            const ts = own(rec, "timestamp");
+            const time = typeof ts === "string" ? Date.parse(ts) : NaN;
+            if (!Number.isFinite(time))
+                continue;
+            const id = own(msg, "id");
+            const key = typeof id === "string" && id ? `id:${id}` : `line:${file}:${i + 1}`;
+            const model = own(msg, "model");
+            // cache_creation_input_tokens already holds the one-hour writes; the one-hour field counts
+            // only when it is the larger, so a line missing the total still counts its writes once.
+            const cacheWrite = Math.max(count(usage.cache_creation_input_tokens), count(own(usage.cache_creation, "ephemeral_1h_input_tokens")));
+            byId.set(key, {
+                time,
+                family: familyOf(typeof model === "string" ? model : "unknown"),
+                cache_read: count(usage.cache_read_input_tokens),
+                fresh: count(usage.input_tokens) + cacheWrite + count(usage.output_tokens),
+            });
+        }
+    }
+    const messages = [...byId.values()].sort((a, b) => a.time - b.time);
+    report.messages = messages.length;
+    return { messages, report };
+}
+/** First index whose time is above `t`, so (start, end] maps to [upper(start), upper(end)). */
+function upper(messages, t) {
+    let lo = 0;
+    let hi = messages.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (messages[mid].time <= t)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function ordered(groups) {
+    const out = {};
+    for (const f of FAMILY_ORDER) {
+        const g = groups.get(f);
+        if (g)
+            out[f] = g;
+    }
+    return out;
+}
+/** Tokens per family in (start, end]; a family with no tokens in the interval is absent. */
+function sumInterval(messages, start, end) {
+    const groups = new Map();
+    for (let i = upper(messages, start), stop = upper(messages, end); i < stop; i++) {
+        const m = messages[i];
+        if (m.cache_read === 0 && m.fresh === 0)
+            continue;
+        const g = groups.get(m.family) ?? { cache_read: 0, fresh: 0 };
+        g.cache_read += m.cache_read;
+        g.fresh += m.fresh;
+        groups.set(m.family, g);
+    }
+    return ordered(groups);
+}
+/**
+ * Solves the least-squares problem on the given columns through the normal equations; a column
+ * dependent on the earlier ones gets 0, which Lawson-Hanson then treats as inactive.
+ */
+function solvePassive(A, b, cols) {
+    const k = cols.length;
+    const G = cols.map((p) => cols.map((q) => A.reduce((s, row) => s + row[p] * row[q], 0)));
+    const y = cols.map((p) => A.reduce((s, row, i) => s + row[p] * b[i], 0));
+    const scale = Math.max(1e-300, ...G.map((row, i) => Math.abs(row[i])));
+    const x = new Array(k).fill(0);
+    const pivotRow = new Array(k).fill(-1);
+    const used = new Array(k).fill(false);
+    for (let c = 0; c < k; c++) {
+        let best = -1;
+        for (let r = 0; r < k; r++)
+            if (!used[r] && (best < 0 || Math.abs(G[r][c]) > Math.abs(G[best][c])))
+                best = r;
+        if (best < 0 || Math.abs(G[best][c]) <= 1e-12 * scale)
+            continue;
+        used[best] = true;
+        pivotRow[c] = best;
+        for (let r = 0; r < k; r++) {
+            if (r === best || G[r][c] === 0)
+                continue;
+            const f = G[r][c] / G[best][c];
+            for (let j = 0; j < k; j++)
+                G[r][j] -= f * G[best][j];
+            y[r] -= f * y[best];
+        }
+    }
+    for (let c = 0; c < k; c++)
+        if (pivotRow[c] >= 0)
+            x[c] = y[pivotRow[c]] / G[pivotRow[c]][c];
+    return x;
+}
+/** Non-negative least squares, Lawson-Hanson (1974): min ||Ax - b|| subject to x >= 0. */
+export function nnls(A, b) {
+    const n = A[0]?.length ?? 0;
+    const x = new Array(n).fill(0);
+    const passive = new Set();
+    const gradient = () => {
+        const r = b.map((bi, i) => bi - A[i].reduce((s, a, j) => s + a * x[j], 0));
+        return Array.from({ length: n }, (_, j) => A.reduce((s, row, i) => s + row[j] * r[i], 0));
+    };
+    const tol = 1e-9 * Math.max(1, ...gradient().map(Math.abs));
+    for (let outer = 0; outer < 3 * n + 3; outer++) {
+        const w = gradient();
+        let j = -1;
+        for (let c = 0; c < n; c++)
+            if (!passive.has(c) && w[c] > tol && (j < 0 || w[c] > w[j]))
+                j = c;
+        if (j < 0)
+            break;
+        passive.add(j);
+        for (let inner = 0; inner < 3 * n + 3; inner++) {
+            const cols = [...passive].sort((p, q) => p - q);
+            const sol = solvePassive(A, b, cols);
+            const s = new Array(n).fill(0);
+            cols.forEach((c, i) => (s[c] = sol[i]));
+            if (cols.every((c) => s[c] > 0)) {
+                for (let c = 0; c < n; c++)
+                    x[c] = s[c];
+                break;
+            }
+            // Step from x toward s only as far as the first passive weight reaching zero.
+            let alpha = 1;
+            for (const c of cols)
+                if (s[c] <= 0)
+                    alpha = Math.min(alpha, x[c] - s[c] > 0 ? x[c] / (x[c] - s[c]) : 0);
+            for (let c = 0; c < n; c++)
+                x[c] += alpha * (s[c] - x[c]);
+            for (const c of cols) {
+                if (x[c] <= 1e-15 || s[c] === 0) {
+                    x[c] = 0;
+                    passive.delete(c);
+                }
+            }
+            if (passive.size === 0)
+                break;
+        }
+    }
+    return x.map((v) => (v > 0 ? v : 0));
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const s = [...values].sort((a, b) => a - b);
+    const mid = s.length >> 1;
+    return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+/**
+ * Fits percent per million tokens per family and group to the intervals' percentage rises.
+ * @param intervals Rows of (delta percent, tokens per family); tokens are raw counts.
+ * @returns The weights of every family with tokens, the interval count and the median absolute
+ *   residual in percentage points; or, below three intervals per feature, the count needed (a
+ *   window without tokens needs at least one family's two features).
+ */
+export function fitWeights(intervals) {
+    const families = FAMILY_ORDER.filter((f) => intervals.some((iv) => (iv.tokens[f]?.cache_read ?? 0) > 0 || (iv.tokens[f]?.fresh ?? 0) > 0));
+    const features = families.length * 2;
+    if (features === 0)
+        return { needed: 2 * INTERVALS_PER_FEATURE, features: 0 };
+    const needed = INTERVALS_PER_FEATURE * features;
+    if (intervals.length < needed)
+        return { needed, features };
+    const A = intervals.map((iv) => families.flatMap((f) => [(iv.tokens[f]?.cache_read ?? 0) / 1e6, (iv.tokens[f]?.fresh ?? 0) / 1e6]));
+    const b = intervals.map((iv) => iv.delta);
+    const x = nnls(A, b);
+    const residuals = A.map((row, i) => Math.abs(b[i] - row.reduce((s, a, j) => s + a * x[j], 0)));
+    const weights = {};
+    families.forEach((f, i) => (weights[f] = { cache_read: clean(x[2 * i]), fresh: clean(x[2 * i + 1]) }));
+    return { weights, residual: clean(median(residuals)), intervals: intervals.length };
+}
+function perPct(tokens, delta) {
+    const out = {};
+    for (const f of FAMILY_ORDER) {
+        const g = tokens[f];
+        if (g)
+            out[f] = { cache_read: clean(g.cache_read / delta), fresh: clean(g.fresh / delta) };
+    }
+    return out;
+}
+/** Reads, forms intervals, sums tokens and fits each window; writes nothing. */
+export function quotaReport(home, days, now = new Date()) {
+    const { readings, report: readingsReport } = readReadings(home, days, now);
+    const formed = formIntervals(readings);
+    const all = [...formed.five_hour, ...formed.seven_day];
+    const earliest = all.length ? Math.min(...all.map((iv) => Date.parse(iv.start.ts))) : Infinity;
+    const { messages, report: transcripts } = all.length ? readMessages(home, earliest) : { messages: [], report: { files: 0, oversize: 0, skipped: 0, messages: 0 } };
+    const windows = {};
+    for (const w of QUOTA_WINDOWS) {
+        const intervals = formed[w].map((iv) => {
+            const tokens = sumInterval(messages, Date.parse(iv.start.ts), Date.parse(iv.end.ts));
+            return { ...iv, tokens, tokens_per_pct: perPct(tokens, iv.delta) };
+        });
+        const fit = fitWeights(intervals);
+        windows[w] =
+            "weights" in fit
+                ? { calibrated: true, interval_count: intervals.length, features: Object.keys(fit.weights).length * 2, needed: INTERVALS_PER_FEATURE * Object.keys(fit.weights).length * 2, weights: fit.weights, residual: fit.residual, intervals }
+                : { calibrated: false, interval_count: intervals.length, features: fit.features, needed: fit.needed, intervals };
+    }
+    return { days, readings: readingsReport, transcripts, windows, note: NOTE, written: null };
+}
+/** At most four significant digits, always with a decimal point, so 2 prints as 2.0. */
+function fmtNum(x) {
+    const s = String(Number(x.toPrecision(4)));
+    return /[.e]/.test(s) ? s : `${s}.0`;
+}
+function fmtCount(n) {
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(2)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(1)}k`;
+    return String(Math.round(n));
+}
+export function formatQuota(report) {
+    const lines = [`quota calibration over the last ${report.days} days`];
+    for (const w of QUOTA_WINDOWS) {
+        const win = report.windows[w];
+        if (win.calibrated && win.weights) {
+            lines.push(`${w}: calibrated from ${win.interval_count} intervals, median absolute residual ${fmtNum(win.residual ?? 0)} percentage points`);
+            for (const [f, g] of Object.entries(win.weights))
+                lines.push(`  ${f}: cache-read ${fmtNum(g.cache_read)}, fresh ${fmtNum(g.fresh)} percent per million tokens`);
+            continue;
+        }
+        const noTokens = win.features === 0 && win.interval_count >= win.needed;
+        lines.push(`${w}: not yet calibrated (${win.interval_count} intervals, ${noTokens ? "none with transcript tokens" : `${win.needed} needed`})`);
+        if (win.intervals.length)
+            lines.push("  tokens per percent of each interval:");
+        for (const iv of win.intervals) {
+            const parts = Object.entries(iv.tokens_per_pct).map(([f, g]) => `${f} cache-read ${fmtCount(g.cache_read)}, fresh ${fmtCount(g.fresh)}`);
+            lines.push(`  ${iv.start.ts} -> ${iv.end.ts} +${fmtNum(iv.delta)} pct: ${parts.length ? `${parts.join("; ")} per percent` : "no transcript tokens"}`);
+        }
+    }
+    lines.push(report.note);
+    const r = report.readings;
+    lines.push(`readings: ${r.lines} lines in range, ${r.malformed} malformed skipped${r.out_of_range ? `, ${r.out_of_range} older than ${report.days} days` : ""}`);
+    for (const s of r.skipped)
+        lines.push(`readings: skipped ${s}`);
+    const t = report.transcripts;
+    lines.push(`transcripts: ${t.files} files read, ${t.oversize} over the size bound skipped${t.skipped ? `, ${t.skipped} not regular files skipped` : ""}`);
+    return lines;
+}
+/** The calibration file's content: calibrated windows only, so a window without a fit never overwrites one. */
+export function calibrationOf(report, now) {
+    const windows = {};
+    for (const w of QUOTA_WINDOWS) {
+        const win = report.windows[w];
+        if (win.calibrated && win.weights)
+            windows[w] = { weights: win.weights, intervals: win.interval_count, residual: win.residual ?? 0 };
+    }
+    return { written: now.toISOString(), days: report.days, windows };
+}
+/**
+ * Replaces the calibration file whole: a temporary file in the same directory, fsync, rename, so
+ * the routing report never reads a half-written file; an existing symlink or non-regular target
+ * is refused rather than replaced.
+ */
+export function writeCalibration(file, calibration) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let existing = null;
+    try {
+        existing = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (existing && !existing.isFile())
+        throw new Error(`refusing to replace ${file}: a symlink or not a regular file`);
+    const tmp = path.join(dir, `.quota-calibration.json.${process.pid}.${Date.now()}.tmp`);
+    const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            fs.writeSync(fd, `${JSON.stringify(calibration, null, 2)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, file);
+    }
+    catch (e) {
+        fs.rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+function validWeights(v) {
+    if (!isPlainObject(v))
+        return "weights is not an object";
+    for (const [f, g] of Object.entries(v)) {
+        if (!FAMILY_ORDER.includes(f))
+            return `unknown family ${JSON.stringify(f).slice(0, 40)}`;
+        for (const k of ["cache_read", "fresh"]) {
+            const n = own(g, k);
+            if (typeof n !== "number" || !Number.isFinite(n) || n < 0)
+                return `${f}.${k} is not a finite number 0 or greater`;
+        }
+    }
+    return null;
+}
+/** Why a parsed calibration fails the data contract, or null when it holds. */
+function calibrationProblem(v) {
+    if (!isPlainObject(v))
+        return "not a JSON object";
+    if (typeof v.written !== "string" || !Number.isFinite(Date.parse(v.written)))
+        return "written is not a timestamp";
+    if (typeof v.days !== "number" || !Number.isSafeInteger(v.days) || v.days <= 0)
+        return "days is not a positive integer";
+    if (!isPlainObject(v.windows))
+        return "windows is not an object";
+    for (const [w, win] of Object.entries(v.windows)) {
+        if (!QUOTA_WINDOWS.includes(w))
+            return `unknown window ${JSON.stringify(w).slice(0, 40)}`;
+        if (!isPlainObject(win))
+            return `${w} is not an object`;
+        const weights = validWeights(win.weights);
+        if (weights)
+            return `${w}: ${weights}`;
+        if (typeof win.intervals !== "number" || !Number.isSafeInteger(win.intervals) || win.intervals <= 0)
+            return `${w}: intervals is not a positive integer`;
+        if (typeof win.residual !== "number" || !Number.isFinite(win.residual) || win.residual < 0)
+            return `${w}: residual is not a finite number 0 or greater`;
+    }
+    return null;
+}
+/**
+ * Reads the calibration for the routing report's window estimate.
+ * @returns The shape-checked calibration; null without a warning when the file is absent; null
+ *   with one `quota calibration ignored: <reason>` line when it is unreadable or off-contract.
+ */
+export function readCalibration(file = quotaCalibrationPath()) {
+    const { text, reason } = readBounded(file, MAX_CALIBRATION_BYTES);
+    if (text === null) {
+        if (reason === "absent")
+            return { calibration: null, warning: null };
+        return { calibration: null, warning: `quota calibration ignored: ${reason === "oversize" ? "over the size bound" : reason === "irregular" ? "a symlink or not a regular file" : "unreadable"}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { calibration: null, warning: "quota calibration ignored: not valid JSON" };
+    }
+    const problem = calibrationProblem(parsed);
+    if (problem)
+        return { calibration: null, warning: `quota calibration ignored: ${problem.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ")}` };
+    return { calibration: parsed, warning: null };
+}
+/**
+ * Runs the calibration and, with `write`, stores the calibrated windows.
+ * @returns The lines to print: the text report, or one JSON document with `--json`.
+ */
+export function costQuota(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const now = opts.now ?? new Date();
+    const report = quotaReport(home, opts.days ?? DEFAULT_QUOTA_DAYS, now);
+    let writeLine = null;
+    if (opts.write) {
+        const calibration = calibrationOf(report, now);
+        const file = quotaCalibrationPath(home);
+        if (Object.keys(calibration.windows).length === 0) {
+            writeLine = `nothing written: no window is calibrated (${file} left as it was)`;
+        }
+        else {
+            writeCalibration(file, calibration);
+            report.written = file;
+            writeLine = `OK   wrote ${file}`;
+        }
+    }
+    if (opts.json)
+        return [JSON.stringify(report, null, 2)];
+    const lines = formatQuota(report);
+    if (writeLine)
+        lines.push(writeLine);
+    return lines;
+}