toolroll 0.9.92 → 0.9.94

package/dist/fenced-check-coverage.js

@@ -0,0 +1,54 @@
+/** Cases that may stay skipped with no CI case behind them, each with why. Product code, reviewed like it: never a file a
+ * release's commits could carry. Empty until a measured run gives a reason. */
+export const FENCED_SKIP_EXEMPTIONS = Object.freeze([]);
+export const unitCaseIdentity = (file, name) => `unit:${file}::${name}`;
+/**
+ * Every case in the macOS CI's reports, by the identity the release check's own reporter gives it (test/release-reporter.ts:
+ * `suite > test`; Vitest's JSON `fullName` joins with spaces, so it can't be matched as it stands). A name twice in a file
+ * passes only if every one of them did. `root` is the checkout the reports name files under.
+ */
+export function macosCases(reports, root) {
+    const cases = new Map();
+    for (const report of reports) {
+        for (const file of report.testResults ?? []) {
+            if (typeof file.name !== "string" || !file.name.startsWith(`${root}/`))
+                continue;
+            const relative = file.name.slice(root.length + 1);
+            for (const one of file.assertionResults ?? []) {
+                if (typeof one.title !== "string")
+                    continue;
+                const ancestors = Array.isArray(one.ancestorTitles) ? one.ancestorTitles.filter((title) => typeof title === "string" && title !== "") : [];
+                const identity = unitCaseIdentity(relative, [...ancestors, one.title].join(" > "));
+                cases.set(identity, (cases.get(identity) ?? true) && one.status === "passed");
+            }
+        }
+    }
+    return cases;
+}
+/** Every case a check's report says it skipped: unit cases and journeys alike. */
+export function skippedCases(report) {
+    const units = (report.units?.identities ?? []).filter(one => one.state === "skipped").map(one => unitCaseIdentity(one.file, one.name));
+    const journeys = report.journeys.flatMap(run => run.groups.flatMap(group => group.journeys.filter(one => one.state === "skipped").map(one => `journey:${run.script}:${run.kind}:${group.group}::${one.name}`)));
+    return [...new Set([...units, ...journeys])].sort();
+}
+/** Each skipped case: passed in that commit's macOS CI, reviewed as exempt, or not covered. */
+export function skipCoverage(skipped, macos, exemptions = FENCED_SKIP_EXEMPTIONS) {
+    const reviewed = new Set(exemptions.map(one => one.identity));
+    const result = { covered: [], exempt: [], uncovered: [] };
+    for (const identity of skipped)
+        (macos.get(identity) === true ? result.covered : reviewed.has(identity) ? result.exempt : result.uncovered).push(identity);
+    return result;
+}
+/** The narrowest level a measured check fully covers. No level covered: `unsandboxed`, as today, with a person's yes. */
+export function measuredLevel(measurements) {
+    for (const level of ["sandboxed", "sign-ins"])
+        if (measurements.some(one => one.level === level && one.passed && one.uncovered === 0))
+            return level;
+    return "unsandboxed";
+}
+/** Why a sandboxed check can't stand for this release, in words a person can act on. */
+export function uncoveredWords(uncovered) {
+    const named = uncovered.slice(0, 5).map(one => one.replace(/^unit:/, "")).join("; ");
+    return `${uncovered.length} ${uncovered.length === 1 ? "case" : "cases"} skipped inside the sandbox ${uncovered.length === 1 ? "isn't" : "aren't"} covered by this commit's macOS CI (${named}${uncovered.length > 5 ? "; and more" : ""}). `
+        + "Widen the project's check access (`toolroll project check-access`, which takes a password) and approve the release again at that level";
+}

package/dist/first-run.js

@@ -145,7 +145,7 @@ export function firstTaskJourney(read, approved, built = false) {
         : read.stage === "checking" || read.stage === "reviewing" ? { index: 3, stuck: false }
             : read.stage === "building" ? { index: 2, stuck: false }
                 // Waiting on nothing a person does: the build finished and is settling.
-                : read.stage === "waiting" ? { index: built ? 3 : 2, stuck: false }
+                : read.stage === "waiting" ? { index: built ? 3 : approved ? 2 : 0, stuck: false }
                     : read.stage === "needs-you" && read.need === "approval" ? { index: 1, stuck: false }
                         : read.stage === "planning" ? { index: 0, stuck: false }
                             : read.stage === "queued" ? { index: approved ? 2 : 0, stuck: false }

package/dist/flaky-ci.d.ts

@@ -0,0 +1,31 @@
+import { type GhRead } from "./nightly-github.js";
+import type { Store } from "./store.js";
+/** How often a project is read at most. */
+export declare const CI_READ_EVERY_MS: number;
+/** The service cursor a project's reads keep (a cursor key can't hold a path). */
+export declare const ciCursorKey: (repo: string) => string;
+/** The GitHub repositories this project's records name: the nightly's opt-in and its failed-checks triggers. */
+export declare function ciRepositoriesOf(store: Store, repo: string): string[];
+export type CiPassResult = {
+    read: number;
+    observed: number;
+    rejected: number;
+};
+/** Pair one run's attempts n-1 and n. A pair already decided isn't read again. */
+export declare function observeCiRun(store: Store, input: {
+    repo: string;
+    slug: string;
+    run: number;
+    sha: string | null;
+    gh: GhRead;
+    now: Date;
+}): Promise<{
+    observed: number;
+    rejected: number;
+}>;
+/** One project's pass over its known runs. A read that fails records nothing and is tried on the next pass. */
+export declare function observeCiAttempts(store: Store, repo: string, gh: GhRead, now: Date): Promise<CiPassResult>;
+/** The storage sweep's own step: CI rows older than the retention window go; nothing else deletes them. */
+export declare function pruneCiObservations(store: Store, now: Date): number;
+/** Pairings refused since `since` for these repositories. */
+export declare function ciNotPaired(store: Store, repositories: readonly string[], since: string): number;

package/dist/flaky-ci.js

@@ -0,0 +1,149 @@
+/**
+ * GitHub CI attempts as mixed outcomes (docs/plans/learning-loops.md, "A CI observation"): read-only, lane level, never
+ * mixed with local pairs, no test name (logs aren't fetched). Only workflow runs Toolroll already knows by id are read:
+ * the watched branch's push runs (`branch_check_run`) and the nightly's runs (`github_nightly_watch`). PR runs aren't
+ * read: Toolroll records no run id for them.
+ *
+ * For a run on attempt n > 1, attempts n-1 and n are read with the exact-attempt reader and paired per lane. A pairing
+ * needs exactly one job per lane in each attempt, both attempts read whole, the same run and commit, an earlier
+ * `failure` that got past setup and a later `success`. Anything else is rejected and counted, never guessed.
+ *
+ * The only writer of `ci_flaky_observation` and `ci_pairing_rejected`. Nothing here reruns anything or changes a check,
+ * a verdict or an approval. A policy path (release-auto.ts EVAL_POLICY).
+ */
+import { createHash } from "node:crypto";
+import { failedBeforeTests } from "./github-jobs.js";
+import { githubNightlyOf, laneIdOf, readAttemptJobs, readRun, resolveLane } from "./nightly-github.js";
+/** How old a known run may be and still be read, how many runs one pass reads, and each read's limit. */
+const RECENT_MS = 14 * 86_400_000;
+const RUNS_PER_PASS = 30;
+const READ_MS = 15_000;
+/** How often a project is read at most. */
+export const CI_READ_EVERY_MS = 30 * 60_000;
+const RETAIN_MS = 180 * 86_400_000;
+/** The service cursor a project's reads keep (a cursor key can't hold a path). */
+export const ciCursorKey = (repo) => `flaky-ci:${createHash("sha256").update(repo).digest("hex").slice(0, 32)}`;
+/** The GitHub repositories this project's records name: the nightly's opt-in and its failed-checks triggers. */
+export function ciRepositoriesOf(store, repo) {
+    const slugs = new Set();
+    const nightly = githubNightlyOf(store, repo);
+    if (nightly !== null)
+        slugs.add(nightly.slug);
+    for (const row of store.handle.prepare("SELECT t.config_json FROM flow_trigger t JOIN flow f ON f.id = t.flow WHERE f.repo = ?").all(repo)) {
+        try {
+            const config = JSON.parse(String(row["config_json"]));
+            if (config.kind === "github" && config.watch === "checks" && typeof config.repo === "string")
+                slugs.add(config.repo);
+        }
+        catch { /* an unreadable trigger names nothing */ }
+    }
+    return [...slugs];
+}
+/** The runs Toolroll knows by id for this project and repository, newest first. */
+function knownRuns(store, repo, slug, now) {
+    const since = new Date(now.getTime() - RECENT_MS).toISOString();
+    const branch = store.handle.prepare("SELECT run_id, head_sha FROM branch_check_run WHERE lower(repo) = lower(?) AND run_created_at >= ? ORDER BY run_created_at DESC, run_id DESC LIMIT ?").all(slug, since, RUNS_PER_PASS)
+        .map(row => ({ id: Number(row["run_id"]), sha: String(row["head_sha"]) }));
+    const nightly = githubNightlyOf(store, repo)?.slug.toLowerCase() === slug.toLowerCase()
+        ? store.handle.prepare("SELECT gh_run FROM github_nightly_watch WHERE repo = ? AND created_at >= ? ORDER BY created_at DESC, gh_run DESC LIMIT ?").all(repo, since, RUNS_PER_PASS).map(row => ({ id: Number(row["gh_run"]), sha: null }))
+        : [];
+    const seen = new Set();
+    return [...branch, ...nightly].filter(one => !seen.has(one.id) && seen.add(one.id) !== undefined).slice(0, RUNS_PER_PASS);
+}
+/** Pair one run's attempts n-1 and n. A pair already decided isn't read again. */
+export async function observeCiRun(store, input) {
+    const { repo, slug, now } = input;
+    const get = (path) => input.gh(path, READ_MS);
+    const run = await readRun(get, slug, input.run);
+    const at = now.toISOString();
+    const rejectedRows = [];
+    const pairs = [];
+    const reject = (attempt, lane, why) => { rejectedRows.push({ attempt, lane, why: lane === null ? why : `${why}: ${lane}` }); };
+    if (run === null)
+        return { observed: 0, rejected: 0 };
+    if (run.runAttempt <= 1 || run.status !== "completed")
+        return { observed: 0, rejected: 0 };
+    const later = run.runAttempt, earlier = later - 1;
+    const decided = store.handle.prepare("SELECT 1 FROM ci_flaky_observation WHERE provider = 'github' AND repository = ? AND workflow_run_id = ? AND passed_attempt = ? UNION ALL SELECT 1 FROM ci_pairing_rejected WHERE provider = 'github' AND repository = ? AND workflow_run_id = ? AND attempt = ? LIMIT 1")
+        .get(slug, input.run, later, slug, input.run, later);
+    if (decided !== undefined)
+        return { observed: 0, rejected: 0 };
+    if (input.sha !== null && input.sha !== run.headSha)
+        reject(later, null, "the run's commit isn't the one recorded");
+    else {
+        const before = await readAttemptJobs(get, slug, run.id, earlier, run.headSha);
+        const after = await readAttemptJobs(get, slug, run.id, later, run.headSha);
+        if (before === null || after === null)
+            reject(later, null, "an attempt couldn't be read whole");
+        else {
+            const laneOf = (job) => resolveLane(store, repo, run.path, job.name) ?? laneIdOf(run.path, job.name);
+            const group = (jobs) => { const lanes = new Map(); for (const job of jobs)
+                lanes.set(laneOf(job), [...(lanes.get(laneOf(job)) ?? []), job]); return lanes; };
+            const was = group(before), now2 = group(after);
+            for (const lane of new Set([...was.keys(), ...now2.keys()])) {
+                const a = was.get(lane) ?? [], b = now2.get(lane) ?? [];
+                if (a.length > 1 || b.length > 1) {
+                    reject(later, lane, "more than one job with this name");
+                    continue;
+                }
+                if (a.length === 0 || b.length === 0) {
+                    reject(later, lane, "the job isn't in both attempts");
+                    continue;
+                }
+                const first = a[0], second = b[0];
+                // A lane that passed both times is the ordinary case, not a pairing refused.
+                if (first.conclusion === "success" && second.conclusion === "success")
+                    continue;
+                if (first.conclusion !== "failure" || second.conclusion !== "success") {
+                    reject(later, lane, `not failure then success (${first.conclusion ?? "no conclusion"}, ${second.conclusion ?? "no conclusion"})`);
+                    continue;
+                }
+                if (first.steps === null || failedBeforeTests({ id: first.id, status: first.status, conclusion: first.conclusion, steps: first.steps })) {
+                    reject(later, lane, "it failed before its tests ran");
+                    continue;
+                }
+                pairs.push({ lane, name: first.name, workflow: run.path, head: run.headSha, failed: first, passed: second, failedAttempt: earlier, passedAttempt: later });
+            }
+        }
+    }
+    let observed = 0, rejected = 0;
+    store.transact(() => {
+        for (const one of pairs) {
+            observed += Number(store.handle.prepare(`INSERT INTO ci_flaky_observation (repo, provider, repository, workflow, lane_id, lane_name, workflow_run_id, head_sha, failed_attempt, failed_job_id, failed_conclusion,
+          passed_attempt, passed_job_id, passed_conclusion, observed_at) VALUES (?, 'github', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (provider, repository, workflow_run_id, lane_id, failed_attempt, passed_attempt) DO NOTHING`)
+                .run(repo, slug, one.workflow, one.lane, one.name, input.run, one.head, one.failedAttempt, one.failed.id, one.failed.conclusion, one.passedAttempt, one.passed.id, one.passed.conclusion, at).changes);
+        }
+        for (const one of rejectedRows) {
+            rejected += Number(store.handle.prepare(`INSERT INTO ci_pairing_rejected (provider, repository, workflow_run_id, attempt, lane_id, why, at) VALUES ('github', ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (provider, repository, workflow_run_id, attempt, why) DO NOTHING`).run(slug, input.run, one.attempt, one.lane, one.why.slice(0, 400), at).changes);
+        }
+    });
+    return { observed, rejected };
+}
+/** One project's pass over its known runs. A read that fails records nothing and is tried on the next pass. */
+export async function observeCiAttempts(store, repo, gh, now) {
+    const result = { read: 0, observed: 0, rejected: 0 };
+    for (const slug of ciRepositoriesOf(store, repo)) {
+        for (const known of knownRuns(store, repo, slug, now)) {
+            const done = await observeCiRun(store, { repo, slug, run: known.id, sha: known.sha, gh, now });
+            result.read++;
+            result.observed += done.observed;
+            result.rejected += done.rejected;
+        }
+    }
+    return result;
+}
+/** The storage sweep's own step: CI rows older than the retention window go; nothing else deletes them. */
+export function pruneCiObservations(store, now) {
+    const cut = new Date(now.getTime() - RETAIN_MS).toISOString();
+    const observed = store.handle.prepare("DELETE FROM ci_flaky_observation WHERE observed_at < ?").run(cut);
+    const rejected = store.handle.prepare("DELETE FROM ci_pairing_rejected WHERE at < ?").run(cut);
+    return Number(observed.changes) + Number(rejected.changes);
+}
+/** Pairings refused since `since` for these repositories. */
+export function ciNotPaired(store, repositories, since) {
+    if (repositories.length === 0)
+        return 0;
+    return Number(store.handle.prepare("SELECT COUNT(*) AS n FROM ci_pairing_rejected WHERE at >= ? AND repository IN (SELECT value FROM json_each(?))").get(since, JSON.stringify(repositories))?.["n"] ?? 0);
+}

package/dist/flaky-cli.d.ts

@@ -0,0 +1,60 @@
+import { type FlakyList, type FlakyRow } from "./flaky.js";
+import type { Store } from "./store.js";
+export declare const FLAKY_DESCRIPTORS: readonly [{
+    readonly action: "list";
+    readonly synopsis: "tests with mixed outcomes under recorded conditions (read only)";
+    readonly mutation: "none";
+    readonly takesQuery: false;
+    readonly flags: readonly [{
+        readonly name: "repo";
+        readonly takesValue: true;
+        readonly meaning: "admitted project checkout root";
+    }, {
+        readonly name: "days";
+        readonly takesValue: true;
+        readonly meaning: "how far back to look (default 90)";
+    }, {
+        readonly name: "json";
+        readonly takesValue: false;
+        readonly meaning: "versioned structured response";
+    }, {
+        readonly name: "db";
+        readonly takesValue: true;
+        readonly meaning: "local Toolroll database";
+    }];
+}, {
+    readonly action: "show";
+    readonly synopsis: "one row's history, and the task that would fix it: flaky show <identity> (read only)";
+    readonly mutation: "none";
+    readonly takesQuery: true;
+    readonly flags: readonly [{
+        readonly name: "repo";
+        readonly takesValue: true;
+        readonly meaning: "admitted project checkout root";
+    }, {
+        readonly name: "days";
+        readonly takesValue: true;
+        readonly meaning: "how far back to look (default 90)";
+    }, {
+        readonly name: "json";
+        readonly takesValue: false;
+        readonly meaning: "versioned structured response";
+    }, {
+        readonly name: "db";
+        readonly takesValue: true;
+        readonly meaning: "local Toolroll database";
+    }];
+}];
+export type FlakyCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    now: Date;
+    actor: string | null;
+    repos: readonly string[];
+};
+/** A row's one line of status, the same words the page says. */
+export declare function flakyStatusWords(row: FlakyRow): string;
+/** How much of the window had per-test reporting, said plainly. */
+export declare function flakyCoverageWords(list: FlakyList): string;
+export declare function runFlakyCommand(positional: readonly string[], options: Map<string, string | true>, context: FlakyCliContext): number;

package/dist/flaky-cli.js

@@ -0,0 +1,60 @@
+/** `toolroll flaky list|show`: the flaky tests list from the terminal, read only. Rerunning stays `task regate`; fixing
+ * one is an ordinary task a person approves (`show` prints it). Nothing here starts a model or changes anything. */
+import { envelopeJson } from "./envelope.js";
+import { FLAKY_WINDOW_DAYS, flakyList, flakyShow } from "./flaky.js";
+const flags = [
+    { name: "repo", takesValue: true, meaning: "admitted project checkout root" },
+    { name: "days", takesValue: true, meaning: `how far back to look (default ${FLAKY_WINDOW_DAYS})` },
+    { name: "json", takesValue: false, meaning: "versioned structured response" },
+    { name: "db", takesValue: true, meaning: "local Toolroll database" },
+];
+export const FLAKY_DESCRIPTORS = [
+    { action: "list", synopsis: "tests with mixed outcomes under recorded conditions (read only)", mutation: "none", takesQuery: false, flags },
+    { action: "show", synopsis: "one row's history, and the task that would fix it: flaky show <identity> (read only)", mutation: "none", takesQuery: true, flags },
+];
+const day = (iso) => iso.slice(0, 10);
+/** A row's one line of status, the same words the page says. */
+export function flakyStatusWords(row) {
+    return row.status === "mixed outcomes" ? "Mixed outcomes" : row.status === "no failures since its file changed" ? "No failures since its file changed" : "Not enough recorded history";
+}
+/** How much of the window had per-test reporting, said plainly. */
+export function flakyCoverageWords(list) {
+    const checks = list.reported + list.unreported;
+    return `Reported by ${list.reported} of ${checks} check${checks === 1 ? "" : "s"}${list.unreported === 0 ? "" : `; ${list.unreported} had no per-test reporting`}.`;
+}
+const rowLine = (row) => `${row.name}\n  ${flakyStatusWords(row)} · ${row.observations} in window · last seen ${day(row.lastSeen)} · ${row.conditions.join(", ") || "conditions not recorded"} · ${row.hardFailures} hard failure${row.hardFailures === 1 ? "" : "s"} · ${row.sources.join(", ") || "no source recorded"}${row.fileChanged === null ? "" : ` · file changed ${day(row.fileChanged)}`}\n  ${row.key}`;
+export function runFlakyCommand(positional, options, context) {
+    const action = positional[0];
+    const command = action ? `flaky ${action}` : "flaky";
+    const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : message); return reason === "usage" ? 2 : 1; };
+    const ok = (result, lines) => { context.write(context.json ? envelopeJson({ ok: true, command, ...result }) : lines.join("\n")); return 0; };
+    if (!FLAKY_DESCRIPTORS.some(one => one.action === action))
+        return fail("usage", "Use flaky list | show <identity> [--repo PATH] [--days N].");
+    if (context.actor === null)
+        return fail("unauthenticated", "Sign in first: the remembered local login drives flaky commands.");
+    const given = options.get("repo");
+    const repo = typeof given === "string" ? given : context.repos.length === 1 ? context.repos[0] : null;
+    if (repo === null)
+        return fail("usage", "Use --repo with the project checkout root.");
+    if (!context.repos.includes(repo))
+        return fail("not-found", "That project is outside your access.");
+    const daysGiven = options.get("days");
+    const days = typeof daysGiven === "string" ? Number(daysGiven) : FLAKY_WINDOW_DAYS;
+    if (!Number.isSafeInteger(days) || days < 1 || days > 730)
+        return fail("usage", "--days takes a whole number from 1 to 730.");
+    if (action === "list") {
+        const list = flakyList(context.store, repo, context.now, days);
+        const history = list.complete ? [] : [`Not enough recorded history: test results are kept for 180 days, so ${days} days can't be counted in full.`];
+        if (list.rows.length === 0)
+            return ok({ list }, [...history, ...(list.complete ? ["No mixed outcomes recorded."] : []), flakyCoverageWords(list)]);
+        return ok({ list }, ["Mixed outcomes under recorded conditions", ...history, ...list.rows.map(rowLine), flakyCoverageWords(list), ...(list.notPaired === 0 ? [] : [`${list.notPaired} GitHub attempt pairing${list.notPaired === 1 ? "" : "s"} not paired.`]), "Not recorded: network, other processes, time of day."]);
+    }
+    const key = positional.slice(1).join(" ").trim();
+    if (key === "")
+        return fail("usage", "flaky show <identity from flaky list>");
+    const found = flakyShow(context.store, repo, key, context.now, days);
+    if (found === null)
+        return fail("not-found", "Nothing is recorded for that test in this project.");
+    return ok(found, [rowLine(found.row), ...found.history.map(one => `  ${day(one.at)} ${one.failed} failed, ${one.passed} passed · ${one.commit ?? "commit not recorded"} · ${one.conditions}`),
+        `Make a task to fix it: toolroll task add "${found.fix.title.replaceAll('"', "'")}" --goal "${found.fix.goal.replaceAll('"', "'")}" --repo ${repo}`]);
+}

package/dist/flaky.d.ts

@@ -0,0 +1,83 @@
+import type { Store } from "./store.js";
+/** Track an identity a local observation named (one row per observation; first write wins, never rewritten). */
+export declare function watchObservation(store: Store, input: {
+    repo: string;
+    identity: string;
+    observation: number;
+    now: Date;
+}): boolean;
+/** How far back the list looks, how long the pruned rows are kept, and how many runs clear a row (the plan's defaults). */
+export declare const FLAKY_WINDOW_DAYS = 90;
+export declare const FLAKY_RETAIN_DAYS = 180;
+export declare const FLAKY_CLEAR_RUNS = 20;
+/** What can be observed at all: a test case, a journey or its group, or a file, never `part:`, `upgrade:`, `check` or
+ * `unexplained`, and never a real-model journey (a model's behaviour isn't a test's flakiness). */
+export declare function observableIdentity(identity: string): boolean;
+/**
+ * Every observation one settled check adds, in the transaction that records its results (check-facts.ts): an in-check
+ * retry, and each identity that failed in one check and explicitly passed in another with equal tree, command, access,
+ * harness and conditions. A `file:` identity is observed only as "failed, then the whole check passed", and only when
+ * no case in that file names the failure. Idempotent: racing dispositions on one pair leave one row.
+ */
+export declare function recordObservations(store: Store, runId: number, now: Date): number[];
+/** The storage sweep's own step: observations older than the retention window go; nothing else deletes them. */
+export declare function pruneObservations(store: Store, now: Date): number;
+export type FlakyStatus = "mixed outcomes" | "no failures since its file changed" | "not enough recorded history";
+export type FlakyRow = {
+    /** The stable handle `flaky show` takes: the identity, or `github:<lane>`. */
+    key: string;
+    kind: "test" | "file" | "lane";
+    /** What the row says, as recorded: untrusted test text, escaped wherever it's shown. */
+    name: string;
+    observations: number;
+    lastSeen: string;
+    /** `<platform>-<arch>-node<major>`, or GitHub for a lane. */
+    conditions: string[];
+    /** Failures under recorded conditions that have no recorded pass. */
+    hardFailures: number;
+    sources: string[];
+    /** When the test's file last changed, as far as the recorded checks show; null when they don't. */
+    fileChanged: string | null;
+    status: FlakyStatus;
+};
+export type FlakyList = {
+    repo: string;
+    days: number;
+    rows: FlakyRow[];
+    /** False when the window reaches past what is kept, so a count there could be short. */
+    complete: boolean;
+    /** CI pairings refused, and how many checks in the window had no per-test reporting. */
+    notPaired: number;
+    unreported: number;
+    reported: number;
+};
+export type FlakyObservation = {
+    kind: "regate" | "same-tree" | "in-check-retry" | "github";
+    at: string;
+    failed: string;
+    passed: string;
+    commit: string | null;
+    conditions: string;
+};
+/** The test file an identity names, when it names one. */
+export declare function identityFile(identity: string): string | null;
+/** A readable name: `<file> › <test>`; a journey's group and name; a file with its limit said. */
+export declare function identityWords(identity: string): string;
+/** Every row for a project: reads only. `days` past the kept window is answered with `complete: false`, never a zero. */
+export declare function flakyList(store: Store, repo: string, now: Date, days?: number): FlakyList;
+/** How many rows the list has now, cheaply: no tree is read. */
+export declare function flakyCount(store: Store, repo: string, now: Date): number;
+/** One row's history, newest first: each observation with both checks (or the CI run and attempts). Null: no such row. */
+export declare function flakyShow(store: Store, repo: string, key: string, now: Date, days?: number): {
+    row: FlakyRow;
+    history: FlakyObservation[];
+    fix: {
+        title: string;
+        goal: string;
+    };
+} | null;
+/** The ordinary task "Make a task to fix it" files; a person approves it as usual. Never to skip or delete the test. */
+export declare function fixTaskOf(row: Pick<FlakyRow, "key" | "name" | "observations" | "conditions" | "kind">): {
+    title: string;
+    goal: string;
+};