@mindlace/chreode 0.1.0 → 0.2.0

package/README.md

@@ -44,6 +44,8 @@ Add `chreode.config.ts` at the repo root (see below), then:
 npx chreode signoff            # merge origin/main, run what changed, push, post the status
 npx chreode signoff --dry-run  # merge, then print the plan and stop
 npx chreode protect            # require the status on main (idempotent); --dry-run previews
+npx chreode flake-report       # report logged flakes to GitHub issues (signoff does this itself)
+npx chreode burn-in --base <sha> --head <sha>  # run changed test files N times, retries off
 ```
 
 Wire them into `package.json` as `"signoff": "chreode signoff"` and
@@ -95,6 +97,96 @@ the repo to squash-only merges that delete head branches. Override either payloa
 `protection` in the config. `--repo owner/name` targets another repo; `--dry-run` prints the
 payloads.
 
+## Flakes
+
+A test that fails and then passes on retry is a flake, and a flake is a bug. chreode records
+each one, files it as a GitHub issue, and fails signoff when the same flake keeps coming back.
+The doctrine and the fix playbook are in [docs/flakes.md](docs/flakes.md).
+
+**1. Record.** Give your runners at least one retry locally and register the reporters. They record only
+tests that pass on a retry, so with retries off nothing is recorded. Both take
+`{ kind?, projects? }`: `kind` (a string, or `(project) => string`) is the issue-title bucket
+(default `'e2e'` for Playwright, the project name or `'unit'` for vitest); `projects` limits
+recording to those runner projects.
+
+```ts
+// playwright.config.ts
+export default defineConfig({
+  retries: 1,
+  use: { trace: 'retain-on-failure' }, // 'on-first-retry' records no trace of the failed attempt
+  reporter: [['list'], ['@mindlace/chreode/reporters/playwright']]
+});
+```
+
+```ts
+// vitest.config.ts (reporters are root-level only)
+import VitestFlakeReporter from '@mindlace/chreode/reporters/vitest';
+
+export default defineConfig({
+  test: { retry: 1, reporters: ['default', new VitestFlakeReporter()] }
+});
+```
+
+Events go to `.chreode/flakes.jsonl` (signoff tells each step the absolute path in
+`CHREODE_FLAKE_LOG`, and the sha under test in `CHREODE_HEAD`). Add `.chreode/` to
+`.gitignore`; when `flakes` is configured, signoff refuses to run otherwise. Registering the
+reporters without a `flakes` block just accumulates events in `.chreode/flakes.jsonl`, unreported.
+Filed issues carry the Playwright trace's local path, valid until the next Playwright run wipes
+`test-results/`, not the trace itself. `playwright` and `vitest` are optional peer
+dependencies: the reporters import only their types.
+
+**2. Ledger.** Add `flakes: {}` to the config. After the steps, pass or fail, signoff gives
+each flaking test one open issue labelled `flake` (the label is created if missing) and adds an
+occurrence comment each time it recurs. At `threshold` occurrences (default 3) signoff fails,
+any run that sees that flake again fails, listing the issue URLs in its failure output (no
+commit status is posted), until the flake is fixed or its issue is labelled `snoozeLabel`
+(default `flake-snoozed`). A run that sees no flake events is silent. A GitHub error is a
+warning: the events not yet recorded stay in the log for the next run.
+`chreode flake-report` runs the same report outside signoff and exits 1 on escalation.
+
+**3. Burn-in.** `burnInStep({ when, timeoutMs? })` adds a step that runs every test file changed since the base
+`repeats` times with retries off, so a new flake fails before it lands rather than after three
+victims. Pass your test steps' triggers as `when`, and place it after them. Its stderr is policed like a
+test step's, so it needs the same `stderrAllowlist` entries:
+
+```ts
+import { burnInStep, defineConfig } from '@mindlace/chreode';
+
+export default defineConfig({
+  steps: [
+    { label: 'test:unit', run: 'npm run test:unit', when: ['unit'], policeStderr: true },
+    { label: 'test:e2e', run: 'npm run test:e2e', when: ['e2e'], policeStderr: true },
+    burnInStep({ when: ['unit', 'e2e'] }) // timeoutMs defaults to 10 minutes
+  ],
+  flakes: {}, // threshold: 3, snoozeLabel: 'flake-snoozed', playbookUrl: chreode's docs/flakes.md on GitHub
+  burnIn: {
+    repeats: 5, // default
+    maxFiles: 12, // default; the overflow is listed, never silently dropped
+    runners: [
+      {
+        name: 'e2e',
+        match: 'e2e/**/*.spec.ts',
+        ignore: 'e2e/helpers/**',
+        // Pin a project: --repeat-each multiplies across every project otherwise.
+        command: (files, n) =>
+          `npx playwright test --project chromium --repeat-each=${n} --retries=0 ${files.join(' ')}`
+      },
+      {
+        name: 'unit',
+        match: 'src/**/*.spec.ts',
+        // vitest has no --repeat-each: return one invocation per repeat.
+        command: (files, n) =>
+          Array.from({ length: n }, () => `npx vitest --run --retry=0 ${files.join(' ')}`)
+      }
+    ]
+  }
+});
+```
+
+A changed file goes to the first runner that matches it and does not `ignore` it; files no
+runner takes are not burned in, and deleted files never are. Commands run from the repo root
+with inherited output; the first failure fails the step and names the files and the command.
+
 ## Config reference
 
 ```ts
@@ -149,6 +241,10 @@ exactly the lockfile, rather than `npm install`, which can rewrite it.
 **`stderrAllowlist`** entries need a `reason`: allowlisting noise is a reviewed decision.
 Unknown keys, duplicate labels, and `supersededBy` naming a missing step are load errors.
 
+**`flakes`** (presence turns flake tracking on) and **`burnIn`** are described under
+[Flakes](#flakes). `threshold`, `repeats` and `maxFiles` must be positive integers, and
+`burnIn.runners` must be non-empty.
+
 ## License
 
 MIT

package/dist/burn-in/run.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedBurnIn } from '../config/types.js';
+import { type Exec, type Run } from '../run/exec.js';
+export interface BurnInDeps {
+    exec: Exec;
+    /** Inherited stdio: the test runners' own output streams through. */
+    run: Run;
+    mtime: (path: string) => number | null;
+    log: (m: string) => void;
+}
+/**
+ * Run every test file added or changed in base..head `repeats` times with retries off. The
+ * first failure exits 1. All of chreode's own output goes to stdout: this runs inside a
+ * policed signoff step.
+ */
+export declare function runBurnIn(config: ResolvedBurnIn | null, range: {
+    base: string;
+    head: string;
+}, overrides?: Partial<BurnInDeps>): number;

package/dist/burn-in/run.js

@@ -0,0 +1,71 @@
+import { statSync } from 'node:fs';
+import { defaultExec, defaultRun } from '../run/exec.js';
+import { BurnInError, burnInCandidates, burnInCommands, selectBurnIn } from './select.js';
+function mtimeOf(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run every test file added or changed in base..head `repeats` times with retries off. The
+ * first failure exits 1. All of chreode's own output goes to stdout: this runs inside a
+ * policed signoff step.
+ */
+export function runBurnIn(config, range, overrides = {}) {
+    const d = {
+        exec: defaultExec,
+        run: (command) => defaultRun(command),
+        mtime: mtimeOf,
+        log: (m) => console.log(m),
+        ...overrides
+    };
+    if (config === null) {
+        d.log('[chreode] burn-in: chreode.config.ts has no burnIn block; nothing knows how to run tests');
+        return 1;
+    }
+    const candidates = burnInCandidates(range.base, range.head, d.exec, d.mtime);
+    const plan = selectBurnIn(candidates, config);
+    let commands;
+    try {
+        commands = burnInCommands(plan, config.repeats);
+    }
+    catch (err) {
+        if (err instanceof BurnInError) {
+            d.log(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    const kept = plan.groups.reduce((n, g) => n + g.files.length, 0);
+    if (kept === 0) {
+        d.log('[chreode] burn-in: no changed test files; nothing to burn in');
+        return 0;
+    }
+    d.log(`[chreode] burn-in: ${kept} changed test file(s) × ${config.repeats}, retries off:`);
+    for (const group of plan.groups) {
+        for (const file of group.files)
+            d.log(`  ${file} (${group.runner.name})`);
+    }
+    if (plan.skipped.length > 0) {
+        d.log(`[chreode] burn-in: over the ${config.maxFiles}-file cap, NOT burned in:`);
+        for (const file of plan.skipped)
+            d.log(`  ${file}`);
+    }
+    for (const c of commands) {
+        d.log(`[chreode] burn-in (${c.runner}): ${c.command}`);
+        try {
+            d.run(c.command);
+        }
+        catch {
+            d.log(`\n[chreode] burn-in FAILED (${c.runner}): ${c.files.join(' ')}\n` +
+                `[chreode] command: ${c.command}\n` +
+                `[chreode] A test that flakes at birth flakes forever: fix it before it lands.`);
+            return 1;
+        }
+    }
+    d.log('[chreode] burn-in: every changed test file survived');
+    return 0;
+}

package/dist/burn-in/select.d.ts

@@ -0,0 +1,30 @@
+import type { BurnInRunner, ResolvedBurnIn } from '../config/types.js';
+import type { Exec } from '../run/exec.js';
+export declare class BurnInError extends Error {
+    constructor(message: string);
+}
+/**
+ * Paths added or modified in base..head, newest mtime first so the file cap keeps the most
+ * recently touched. --no-renames lists a rename as delete + add and --diff-filter=d drops
+ * deletions, so a renamed file appears under its new name only. Files missing on disk
+ * (mtime null) are dropped.
+ */
+export declare function burnInCandidates(base: string, head: string, exec: Exec, mtime: (path: string) => number | null): string[];
+/** The first runner that matches the path and does not ignore it. */
+export declare function runnerFor(path: string, runners: readonly BurnInRunner[]): BurnInRunner | null;
+export interface BurnInGroup {
+    runner: BurnInRunner;
+    files: string[];
+}
+export interface BurnInPlan {
+    groups: BurnInGroup[];
+    /** Burnable files past maxFiles: listed, never silently dropped. */
+    skipped: string[];
+}
+export declare function selectBurnIn(paths: readonly string[], config: ResolvedBurnIn): BurnInPlan;
+export interface BurnInCommand {
+    runner: string;
+    files: string[];
+    command: string;
+}
+export declare function burnInCommands(plan: BurnInPlan, repeats: number): BurnInCommand[];

package/dist/burn-in/select.js

@@ -0,0 +1,78 @@
+import { matchesAny } from '../signoff/plan.js';
+export class BurnInError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BurnInError';
+    }
+}
+/**
+ * Paths added or modified in base..head, newest mtime first so the file cap keeps the most
+ * recently touched. --no-renames lists a rename as delete + add and --diff-filter=d drops
+ * deletions, so a renamed file appears under its new name only. Files missing on disk
+ * (mtime null) are dropped.
+ */
+export function burnInCandidates(base, head, exec, mtime) {
+    if (base === head)
+        return [];
+    const out = exec('git', [
+        'diff',
+        '--name-only',
+        '--no-renames',
+        '--diff-filter=d',
+        '-z',
+        `${base}..${head}`
+    ]);
+    return out
+        .split('\0')
+        .filter((p) => p !== '')
+        .map((path) => ({ path, time: mtime(path) }))
+        .filter((c) => c.time !== null)
+        .sort((a, b) => b.time - a.time)
+        .map((c) => c.path);
+}
+/** The first runner that matches the path and does not ignore it. */
+export function runnerFor(path, runners) {
+    for (const runner of runners) {
+        if (!matchesAny(path, runner.match))
+            continue;
+        if (runner.ignore !== undefined && matchesAny(path, runner.ignore))
+            continue;
+        return runner;
+    }
+    return null;
+}
+export function selectBurnIn(paths, config) {
+    const byRunner = new Map();
+    const skipped = [];
+    let kept = 0;
+    for (const path of paths) {
+        const runner = runnerFor(path, config.runners);
+        if (runner === null)
+            continue;
+        if (kept >= config.maxFiles) {
+            skipped.push(path);
+            continue;
+        }
+        byRunner.set(runner, [...(byRunner.get(runner) ?? []), path]);
+        kept += 1;
+    }
+    const groups = config.runners
+        .filter((runner) => byRunner.has(runner))
+        .map((runner) => ({ runner, files: byRunner.get(runner) }));
+    return { groups, skipped };
+}
+export function burnInCommands(plan, repeats) {
+    const out = [];
+    for (const { runner, files } of plan.groups) {
+        const produced = runner.command([...files], repeats);
+        const commands = Array.isArray(produced) ? produced : [produced];
+        const ok = commands.length > 0 && commands.every((c) => typeof c === 'string' && c.trim() !== '');
+        if (!ok) {
+            throw new BurnInError(`burnIn runner "${runner.name}": command() must return a non-empty command or a ` +
+                `non-empty array of them`);
+        }
+        for (const command of commands)
+            out.push({ runner: runner.name, files, command });
+    }
+    return out;
+}

package/dist/burn-in/step.d.ts

@@ -0,0 +1,10 @@
+import { type StepConfig } from '../config/types.js';
+export declare const BURN_IN_LABEL = "burn-in";
+export interface BurnInStepOptions {
+    /** The triggers of your test steps: chreode cannot tell which steps are tests. */
+    when: string[];
+    timeoutMs?: number;
+}
+/** A signoff step that burns in the test files changed since the base. Place it after the
+ *  test steps. */
+export declare function burnInStep(opts: BurnInStepOptions): StepConfig;

package/dist/burn-in/step.js

@@ -0,0 +1,14 @@
+import { DEFAULT_TIMEOUT_MS } from '../config/types.js';
+export const BURN_IN_LABEL = 'burn-in';
+/** A signoff step that burns in the test files changed since the base. Place it after the
+ *  test steps. */
+export function burnInStep(opts) {
+    return {
+        label: BURN_IN_LABEL,
+        run: ({ base, head }) => `npx chreode burn-in --base ${base} --head ${head}`,
+        when: [...opts.when],
+        if: ({ base, head }) => base !== head,
+        policeStderr: true,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    };
+}

package/dist/cli.d.ts

@@ -16,11 +16,21 @@ export interface ProtectFlags {
     repo?: string;
     config?: string;
 }
+export interface FlakeReportFlags {
+    config?: string;
+}
+export interface BurnInFlags {
+    base: string;
+    head: string;
+    config?: string;
+}
 /** Each flag also has an env form, for harnesses that forbid flags after `--`. */
 export declare function resolveSignoffOptions(flags: SignoffFlags, env: NodeJS.ProcessEnv): SignoffOptions;
 export declare function buildProgram(actions: {
     signoff: (flags: SignoffFlags) => Promise<number>;
     protect: (flags: ProtectFlags) => Promise<number>;
+    flakeReport: (flags: FlakeReportFlags) => Promise<number>;
+    burnIn: (flags: BurnInFlags) => Promise<number>;
 }, setExit: (code: number) => void): Command;
 export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<number>;
 /** npm installs the bin as a symlink, so compare real paths, not the invoked path. */

package/dist/cli.js

@@ -3,7 +3,9 @@ import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
+import { runBurnIn } from './burn-in/run.js';
 import { CONFIG_FILE, loadConfig } from './config/load.js';
+import { runFlakeReport } from './flakes/report.js';
 import { parseRepo } from './github/status.js';
 import { runProtect } from './github/protect.js';
 import { defaultExec } from './run/exec.js';
@@ -50,6 +52,18 @@ export function buildProgram(actions, setExit) {
         .option('--repo <owner/name>', 'target repository (default: gh repo view)')
         .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
         .action(async (flags) => setExit(await actions.protect(flags)));
+    program
+        .command('flake-report')
+        .description('report logged flakes to GitHub issues; exit 1 if any reached the threshold')
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.flakeReport(flags)));
+    program
+        .command('burn-in')
+        .description('run the test files changed in base..head repeatedly, with retries off')
+        .requiredOption('--base <sha>', 'diff from this commit')
+        .requiredOption('--head <sha>', 'diff to this commit')
+        .option('--config <path>', `config file (default: <repo root>/${CONFIG_FILE})`)
+        .action(async (flags) => setExit(await actions.burnIn(flags)));
     return program;
 }
 /** Steps and git commands run from the repo root, whatever directory chreode was started in.
@@ -68,6 +82,11 @@ export async function main(argv = process.argv, env = process.env) {
         protect: async (flags) => runProtect(await repoConfigLoader(flags.config)(), {
             dryRun: flags.dryRun === true,
             repo: flags.repo ? parseRepo(flags.repo) : null
+        }),
+        flakeReport: async (flags) => runFlakeReport(await repoConfigLoader(flags.config)()),
+        burnIn: async (flags) => runBurnIn((await repoConfigLoader(flags.config)()).burnIn, {
+            base: flags.base,
+            head: flags.head
         })
     }, (c) => {
         code = c;

package/dist/config/types.d.ts

@@ -40,6 +40,39 @@ export interface ProtectionConfig {
     /** Shallow-merged over the default repository merge settings. */
     repo?: Record<string, unknown>;
 }
+/** Presence turns flake tracking on: retried-then-passed tests become GitHub issues. */
+export interface FlakesConfig {
+    /** Occurrences (the issue itself counts as one) at which an unsnoozed flake fails signoff. */
+    threshold?: number;
+    /** An issue carrying this label never escalates. */
+    snoozeLabel?: string;
+    /** Linked from every filed issue. */
+    playbookUrl?: string;
+}
+export interface BurnInRunner {
+    /** For output. */
+    name: string;
+    match: Matcher | Matcher[];
+    ignore?: Matcher | Matcher[];
+    /** A string runs once; an array runs each in sequence (for runners with no repeat flag). */
+    command: (files: string[], repeats: number) => string | string[];
+}
+export interface BurnInConfig {
+    repeats?: number;
+    /** Changed test files beyond this many are listed as skipped, never silently dropped. */
+    maxFiles?: number;
+    runners: BurnInRunner[];
+}
+export interface ResolvedFlakes {
+    threshold: number;
+    snoozeLabel: string;
+    playbookUrl: string;
+}
+export interface ResolvedBurnIn {
+    repeats: number;
+    maxFiles: number;
+    runners: BurnInRunner[];
+}
 export interface ChreodeConfig {
     baseBranch?: string;
     statusContext?: string;
@@ -49,6 +82,8 @@ export interface ChreodeConfig {
     afterMerge?: string;
     stderrAllowlist?: AllowlistEntry[];
     protection?: ProtectionConfig;
+    flakes?: FlakesConfig;
+    burnIn?: BurnInConfig;
 }
 export interface ResolvedStep extends StepConfig {
     supersededBy: string[];
@@ -63,9 +98,17 @@ export interface ResolvedConfig {
     afterMerge: string | null;
     stderrAllowlist: AllowlistEntry[];
     protection: ProtectionConfig;
+    flakes: ResolvedFlakes | null;
+    burnIn: ResolvedBurnIn | null;
 }
 export declare const DEFAULT_BASE_BRANCH = "main";
 export declare const DEFAULT_STATUS_CONTEXT = "chreode/signoff";
 export declare const DEFAULT_TIMEOUT_MS: number;
+export declare const DEFAULT_FLAKE_THRESHOLD = 3;
+export declare const DEFAULT_SNOOZE_LABEL = "flake-snoozed";
+export declare const DEFAULT_PLAYBOOK_URL = "https://github.com/mindlace/chreode/blob/main/docs/flakes.md";
+export declare const DEFAULT_BURN_IN_REPEATS = 5;
+export declare const DEFAULT_BURN_IN_MAX_FILES = 12;
+export declare function resolveFlakes(config: FlakesConfig): ResolvedFlakes;
 /** Identity helper so `chreode.config.ts` gets types. */
 export declare function defineConfig(config: ChreodeConfig): ChreodeConfig;

package/dist/config/types.js

@@ -1,6 +1,18 @@
 export const DEFAULT_BASE_BRANCH = 'main';
 export const DEFAULT_STATUS_CONTEXT = 'chreode/signoff';
 export const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_FLAKE_THRESHOLD = 3;
+export const DEFAULT_SNOOZE_LABEL = 'flake-snoozed';
+export const DEFAULT_PLAYBOOK_URL = 'https://github.com/mindlace/chreode/blob/main/docs/flakes.md';
+export const DEFAULT_BURN_IN_REPEATS = 5;
+export const DEFAULT_BURN_IN_MAX_FILES = 12;
+export function resolveFlakes(config) {
+    return {
+        threshold: config.threshold ?? DEFAULT_FLAKE_THRESHOLD,
+        snoozeLabel: config.snoozeLabel ?? DEFAULT_SNOOZE_LABEL,
+        playbookUrl: config.playbookUrl ?? DEFAULT_PLAYBOOK_URL
+    };
+}
 /** Identity helper so `chreode.config.ts` gets types. */
 export function defineConfig(config) {
     return config;

package/dist/config/validate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_BRANCH, DEFAULT_STATUS_CONTEXT, DEFAULT_TIMEOUT_MS } from './types.js';
+import { DEFAULT_BASE_BRANCH, DEFAULT_BURN_IN_MAX_FILES, DEFAULT_BURN_IN_REPEATS, DEFAULT_STATUS_CONTEXT, DEFAULT_TIMEOUT_MS, resolveFlakes } from './types.js';
 export class ConfigError extends Error {
     problems;
     constructor(problems) {
@@ -14,7 +14,9 @@ const TOP_KEYS = new Set([
     'steps',
     'afterMerge',
     'stderrAllowlist',
-    'protection'
+    'protection',
+    'flakes',
+    'burnIn'
 ]);
 const RULE_KEYS = new Set(['match', 'triggers']);
 const STEP_KEYS = new Set([
@@ -28,6 +30,10 @@ const STEP_KEYS = new Set([
 ]);
 const ALLOW_KEYS = new Set(['pattern', 'reason']);
 const PROTECTION_KEYS = new Set(['branch', 'repo']);
+const FLAKES_KEYS = new Set(['threshold', 'snoozeLabel', 'playbookUrl']);
+const BURN_IN_KEYS = new Set(['repeats', 'maxFiles', 'runners']);
+const RUNNER_KEYS = new Set(['name', 'match', 'ignore', 'command']);
+const MATCHER_PROBLEM = 'must be a glob string, a RegExp, or a non-empty array of them';
 /** Cross-realm safe: a config evaluated by jiti may not share this realm's RegExp. */
 export function isRegExp(v) {
     return Object.prototype.toString.call(v) === '[object RegExp]';
@@ -44,6 +50,12 @@ function isStringArray(v) {
 function isMatcher(v) {
     return isNonEmptyString(v) || isRegExp(v);
 }
+function isMatcherList(v) {
+    return Array.isArray(v) ? v.length > 0 && v.every(isMatcher) : isMatcher(v);
+}
+function isPositiveInteger(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
 function unknownKeys(obj, allowed, where, problems) {
     for (const key of Object.keys(obj)) {
         if (!allowed.has(key))
@@ -64,11 +76,8 @@ function validateRules(raw, problems) {
             return;
         }
         unknownKeys(rule, RULE_KEYS, where, problems);
-        const m = rule.match;
-        const ok = Array.isArray(m) ? m.length > 0 && m.every(isMatcher) : isMatcher(m);
-        if (!ok) {
-            problems.push(`${where}.match: must be a glob string, a RegExp, or a non-empty array of them`);
-        }
+        if (!isMatcherList(rule.match))
+            problems.push(`${where}.match: ${MATCHER_PROBLEM}`);
         if (!Array.isArray(rule.triggers) || !rule.triggers.every(isNonEmptyString)) {
             problems.push(`${where}.triggers: must be an array of trigger names ([] means "matched, run nothing")`);
         }
@@ -173,6 +182,67 @@ function validateProtection(raw, problems) {
     }
     return raw;
 }
+function validateFlakes(raw, problems) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        problems.push('config.flakes: must be an object ({} turns flake tracking on with the defaults)');
+        return null;
+    }
+    unknownKeys(raw, FLAKES_KEYS, 'flakes', problems);
+    if (raw.threshold !== undefined && !isPositiveInteger(raw.threshold)) {
+        problems.push('flakes.threshold: must be a positive integer');
+    }
+    for (const key of ['snoozeLabel', 'playbookUrl']) {
+        if (raw[key] !== undefined && !isNonEmptyString(raw[key])) {
+            problems.push(`flakes.${key}: must be a non-empty string`);
+        }
+    }
+    return resolveFlakes(raw);
+}
+function validateBurnIn(raw, problems) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        problems.push('config.burnIn: must be an object');
+        return null;
+    }
+    unknownKeys(raw, BURN_IN_KEYS, 'burnIn', problems);
+    for (const key of ['repeats', 'maxFiles']) {
+        if (raw[key] !== undefined && !isPositiveInteger(raw[key])) {
+            problems.push(`burnIn.${key}: must be a positive integer`);
+        }
+    }
+    const runners = raw.runners;
+    if (!Array.isArray(runners) || runners.length === 0) {
+        problems.push('burnIn.runners: must be a non-empty array');
+    }
+    else {
+        runners.forEach((runner, i) => {
+            const where = `burnIn.runners[${i}]`;
+            if (!isRecord(runner)) {
+                problems.push(`${where}: must be an object`);
+                return;
+            }
+            unknownKeys(runner, RUNNER_KEYS, where, problems);
+            if (!isNonEmptyString(runner.name))
+                problems.push(`${where}.name: must be a non-empty string`);
+            if (!isMatcherList(runner.match))
+                problems.push(`${where}.match: ${MATCHER_PROBLEM}`);
+            if (runner.ignore !== undefined && !isMatcherList(runner.ignore)) {
+                problems.push(`${where}.ignore: ${MATCHER_PROBLEM}`);
+            }
+            if (typeof runner.command !== 'function') {
+                problems.push(`${where}.command: must be a function (files, repeats) => string | string[]`);
+            }
+        });
+    }
+    return {
+        repeats: raw.repeats ?? DEFAULT_BURN_IN_REPEATS,
+        maxFiles: raw.maxFiles ?? DEFAULT_BURN_IN_MAX_FILES,
+        runners: Array.isArray(runners) ? runners : []
+    };
+}
 export function validateConfig(raw) {
     if (!isRecord(raw)) {
         throw new ConfigError([
@@ -190,6 +260,8 @@ export function validateConfig(raw) {
     const steps = validateSteps(raw.steps, problems);
     const stderrAllowlist = validateAllowlist(raw.stderrAllowlist, problems);
     const protection = validateProtection(raw.protection, problems);
+    const flakes = validateFlakes(raw.flakes, problems);
+    const burnIn = validateBurnIn(raw.burnIn, problems);
     if (problems.length > 0)
         throw new ConfigError(problems);
     return {
@@ -199,6 +271,8 @@ export function validateConfig(raw) {
         steps,
         afterMerge: raw.afterMerge ?? null,
         stderrAllowlist,
-        protection
+        protection,
+        flakes,
+        burnIn
     };
 }

package/dist/flakes/gh.d.ts

@@ -0,0 +1,5 @@
+import { type Exec } from '../run/exec.js';
+import { type FlakeLedgerDeps } from './ledger.js';
+/** The ledger's GitHub side over `gh`. Every call is argv (no shell), so test titles and
+ *  error text reach GitHub verbatim. */
+export declare function ghLedgerDeps(exec?: Exec): FlakeLedgerDeps;