@evomap/evolver-core 2.0.0-beta.0

package/dist/benchmark/antiGeneRollout.d.ts

@@ -0,0 +1,80 @@
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import { ReviewLedger } from '../assetstore/reviewLedger.js';
+import type { ReportEvent } from '../events/reports.js';
+import { type CycleInput } from '../algo/cycleEngine.js';
+import type { GepCategory } from '../wire/index.js';
+export type AntiGeneRolloutArm = 'baseline' | 'antiGene';
+export type AntiGeneRolloutVerdict = 'anti_gene_better' | 'no_clear_improvement' | 'anti_gene_worse' | 'insufficient_samples';
+export interface AntiGeneRolloutTask {
+    id: string;
+    signals: string[];
+    target?: string;
+    expectedEffect?: string;
+    category?: GepCategory;
+    summary?: string;
+    confidence?: number;
+    expectedAntiWarnings?: string[];
+}
+export interface AntiGeneRolloutSuite {
+    name: string;
+    validation?: string[];
+    tasks: AntiGeneRolloutTask[];
+}
+export interface AntiGeneRolloutArmMetrics {
+    arm: AntiGeneRolloutArm;
+    n: number;
+    failures: number;
+    failureRate: number;
+    repeatedFailures: number;
+    overblocked: number;
+    observedWarnings: number;
+}
+export interface AntiGeneRolloutRunResult {
+    status: 'success' | 'failed';
+    score: number;
+    repeatedFailure: boolean;
+    overblocked: boolean;
+    observedAntiWarnings: string[];
+    missingExpectedWarnings: string[];
+    selectedGeneId?: string | null;
+}
+export interface AntiGeneRolloutTaskResult {
+    taskId: string;
+    baseline: AntiGeneRolloutRunResult;
+    antiGene: AntiGeneRolloutRunResult;
+}
+export interface AntiGeneRolloutReport {
+    suite: string;
+    tasks: number;
+    baseline: AntiGeneRolloutArmMetrics;
+    antiGene: AntiGeneRolloutArmMetrics;
+    missingExpectedWarnings: number;
+    overblocked: number;
+    failureDelta: number;
+    verdict: AntiGeneRolloutVerdict;
+    taskResults: AntiGeneRolloutTaskResult[];
+    taskResultsTruncated?: number;
+}
+export interface AntiGeneRolloutExecuteContext {
+    arm: AntiGeneRolloutArm;
+    task: AntiGeneRolloutTask;
+    store: AssetStoreProvider;
+    review: ReviewLedger;
+    armDir: string;
+}
+export type AntiGeneRolloutExecuteFactory = (context: AntiGeneRolloutExecuteContext) => CycleInput['execute'];
+export interface AntiGeneRolloutDeps {
+    store: AssetStoreProvider;
+    review?: ReviewLedger;
+    makeExecute: AntiGeneRolloutExecuteFactory;
+}
+export interface AntiGeneRolloutOptions {
+    minSamples?: number;
+    minFailureDelta?: number;
+    now?: () => number;
+    eventsPath?: string;
+}
+export declare function runAntiGeneRollout(suite: AntiGeneRolloutSuite, deps: AntiGeneRolloutDeps, options?: AntiGeneRolloutOptions): Promise<AntiGeneRolloutReport>;
+export declare function writeAntiGeneRolloutResult(report: AntiGeneRolloutReport, eventsPath: string, now?: () => number): Promise<void>;
+export declare function antiGeneRolloutReportsFromEvents(events: readonly ReportEvent[]): AntiGeneRolloutReport[];
+export declare function latestAntiGeneRolloutReport(events: readonly ReportEvent[]): AntiGeneRolloutReport | null;

package/dist/benchmark/antiGeneRollout.js

@@ -0,0 +1,256 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { LocalJsonlProvider } from '../assetstore/localJsonl.js';
+import { ReviewLedger } from '../assetstore/reviewLedger.js';
+import { Ingestor } from '../events/ingest.js';
+import { LineTooLargeError } from '../events/eventStore.js';
+import { CycleEngine } from '../algo/cycleEngine.js';
+import { runEvolutionCycle } from '../algo/orchestrator.js';
+import { makeGeneSelectionPoint } from '../algo/geneSelection.js';
+const ALL_ASSETS_LIMIT = Number.MAX_SAFE_INTEGER;
+const ASSET_KINDS = ['Gene', 'Capsule', 'EvolutionEvent', 'AntiGene'];
+function buildProblem(task, now) {
+    return {
+        id: task.id,
+        signature: `anti-gene-rollout:${task.id}`,
+        signatureV: 1,
+        firstSeenAt: new Date(now - 1000).toISOString(),
+        lastSeenAt: new Date(now).toISOString(),
+        occurrences: 3,
+        linkedSignals: task.signals,
+        resolvedBy: null,
+        status: 'open',
+        value: { severity: 1, reach: 1, strategicFit: 1, novelty: 0, costEst: 0 },
+        consecutiveFailures: 0,
+        cooldownUntil: null,
+        extensions: {},
+    };
+}
+async function copyAssets(source, dest, includeApprovedAntiGenes, sourceReview) {
+    for (const kind of ASSET_KINDS) {
+        for (const asset of await source.list(kind, ALL_ASSETS_LIMIT)) {
+            if (kind === 'AntiGene') {
+                if (!includeApprovedAntiGenes)
+                    continue;
+                if (sourceReview.get(String(asset.asset_id))?.state !== 'approved')
+                    continue;
+            }
+            await dest.put(asset);
+        }
+    }
+}
+function copyReview(source, dest) {
+    for (const record of source.records()) {
+        dest.mark({
+            assetId: record.assetId,
+            state: record.state,
+            ...(record.by ? { by: record.by } : {}),
+            ...(record.reason ? { reason: record.reason } : {}),
+            at: record.at,
+        });
+    }
+}
+function defaultReviewForStore(store, now) {
+    const baseDir = store.baseDir;
+    return typeof baseDir === 'string' ? new ReviewLedger(baseDir, now) : null;
+}
+function observedWarningIds(decision) {
+    if (!decision || typeof decision !== 'object')
+        return [];
+    const warnings = decision.antiWarnings;
+    if (!Array.isArray(warnings))
+        return [];
+    return warnings
+        .map((warning) => {
+        if (!warning || typeof warning !== 'object' || Array.isArray(warning))
+            return '';
+        const row = warning;
+        return String(row.antiGeneId ?? row.assetId ?? '');
+    })
+        .filter(Boolean);
+}
+function missingExpected(expected, observed) {
+    const seen = new Set(observed);
+    return (expected ?? []).filter((id) => !seen.has(id));
+}
+function statusFromResult(result) {
+    return result.finalStage === 'solidified' ? 'success' : 'failed';
+}
+function scoreFromResult(result, status) {
+    const score = result.capsule?.outcome?.score;
+    return typeof score === 'number' && Number.isFinite(score) ? score : status === 'success' ? 0.9 : 0.2;
+}
+async function runOneArm(arm, task, source, sourceReview, makeExecute, rootDir, now) {
+    const armDir = join(rootDir, arm, task.id);
+    const store = new LocalJsonlProvider(join(armDir, 'assets'));
+    const review = new ReviewLedger(join(armDir, 'assets'), now);
+    await copyAssets(source, store, arm === 'antiGene', sourceReview);
+    copyReview(sourceReview, review);
+    const eventPath = join(armDir, 'events.jsonl');
+    const engine = new CycleEngine({
+        ingestor: new Ingestor({ path: eventPath, now }),
+        selection: makeGeneSelectionPoint(),
+        store,
+        now,
+    });
+    const opts = {
+        cycleId: `${arm}-${task.id}`,
+        problem: buildProblem(task, now()),
+        signals: task.signals,
+        category: task.category ?? 'repair',
+        target: task.target ?? 't.ts',
+        expectedEffect: task.expectedEffect ?? `anti-gene rollout ${task.id}`,
+        summary: task.summary ?? `anti-gene rollout ${task.id}`,
+        confidence: task.confidence ?? 0.9,
+        execute: makeExecute({ arm, task, store, review, armDir }),
+        review,
+        consumePendingSignals: false,
+    };
+    const result = await runEvolutionCycle(engine, store, opts);
+    const status = statusFromResult(result);
+    const observed = observedWarningIds(result.decision);
+    return {
+        status,
+        score: scoreFromResult(result, status),
+        repeatedFailure: status === 'failed' && (task.expectedAntiWarnings?.length ?? 0) > 0,
+        overblocked: false,
+        observedAntiWarnings: observed,
+        missingExpectedWarnings: arm === 'antiGene' ? missingExpected(task.expectedAntiWarnings, observed) : [],
+        selectedGeneId: result.decision?.selectedGeneId ?? null,
+    };
+}
+function armMetrics(arm, results) {
+    const n = results.length;
+    const failures = results.filter((r) => r.status === 'failed').length;
+    return {
+        arm,
+        n,
+        failures,
+        failureRate: n > 0 ? failures / n : 0,
+        repeatedFailures: results.filter((r) => r.repeatedFailure).length,
+        overblocked: results.filter((r) => r.overblocked).length,
+        observedWarnings: results.reduce((sum, r) => sum + r.observedAntiWarnings.length, 0),
+    };
+}
+function verdict(report, minSamples, minFailureDelta) {
+    if (report.baseline.n < minSamples || report.antiGene.n < minSamples)
+        return 'insufficient_samples';
+    if (report.failureDelta >= minFailureDelta && report.antiGene.observedWarnings > 0 && report.missingExpectedWarnings === 0)
+        return 'anti_gene_better';
+    if (report.failureDelta < -minFailureDelta || (minFailureDelta === 0 && report.failureDelta < 0))
+        return 'anti_gene_worse';
+    return 'no_clear_improvement';
+}
+function normalizeTaskResults(taskResults) {
+    return taskResults.map((task) => {
+        const overblocked = task.baseline.status === 'success' && task.antiGene.status === 'failed';
+        return {
+            taskId: task.taskId,
+            baseline: { ...task.baseline, overblocked: false },
+            antiGene: { ...task.antiGene, overblocked, repeatedFailure: overblocked ? false : task.antiGene.repeatedFailure },
+        };
+    });
+}
+function buildReport(suite, rawTaskResults, minSamples, minFailureDelta) {
+    const taskResults = normalizeTaskResults(rawTaskResults);
+    const baseline = armMetrics('baseline', taskResults.map((r) => r.baseline));
+    const antiGene = armMetrics('antiGene', taskResults.map((r) => r.antiGene));
+    const partial = {
+        suite: suite.name,
+        tasks: suite.tasks.length,
+        baseline,
+        antiGene,
+        missingExpectedWarnings: taskResults.reduce((sum, r) => sum + r.antiGene.missingExpectedWarnings.length, 0),
+        overblocked: antiGene.overblocked,
+        failureDelta: baseline.failureRate - antiGene.failureRate,
+        taskResults,
+    };
+    return { ...partial, verdict: verdict(partial, minSamples, minFailureDelta) };
+}
+export async function runAntiGeneRollout(suite, deps, options = {}) {
+    const now = options.now ?? Date.now;
+    const sourceReview = deps.review ?? defaultReviewForStore(deps.store, now);
+    if (!sourceReview)
+        throw new Error('AntiGene rollout requires a ReviewLedger or a LocalJsonlProvider-backed store so review state can be copied');
+    const minSamples = options.minSamples ?? 30;
+    const minFailureDelta = options.minFailureDelta ?? 0.05;
+    const rootDir = mkdtempSync(join(tmpdir(), 'anti-gene-rollout-'));
+    try {
+        const taskResults = [];
+        for (const task of suite.tasks) {
+            taskResults.push({
+                taskId: task.id,
+                baseline: await runOneArm('baseline', task, deps.store, sourceReview, deps.makeExecute, rootDir, now),
+                antiGene: await runOneArm('antiGene', task, deps.store, sourceReview, deps.makeExecute, rootDir, now),
+            });
+        }
+        const report = buildReport(suite, taskResults, minSamples, minFailureDelta);
+        if (options.eventsPath)
+            await writeAntiGeneRolloutResult(report, options.eventsPath, now);
+        return report;
+    }
+    finally {
+        rmSync(rootDir, { recursive: true, force: true });
+    }
+}
+export async function writeAntiGeneRolloutResult(report, eventsPath, now = Date.now) {
+    const ingestor = new Ingestor({ path: eventsPath, now });
+    try {
+        await ingestReportPayload(ingestor, report);
+    }
+    catch (error) {
+        if (!(error instanceof LineTooLargeError))
+            throw error;
+        await ingestReportPayload(ingestor, compactReportPayload(report, 5));
+    }
+}
+async function ingestReportPayload(ingestor, payload) {
+    await ingestor.ingest({
+        type: 'anti_gene.rollout_result',
+        human: { title: `anti-gene rollout ${payload.suite}` },
+        payload: payload,
+        actor: { kind: 'machine', id: 'anti-gene-rollout' },
+    });
+}
+function compactWarnings(items) {
+    return items.slice(0, 3);
+}
+function compactRunResult(result) {
+    return {
+        ...result,
+        observedAntiWarnings: compactWarnings(result.observedAntiWarnings),
+        missingExpectedWarnings: compactWarnings(result.missingExpectedWarnings),
+    };
+}
+function compactReportPayload(report, maxTasks) {
+    return {
+        ...report,
+        taskResults: report.taskResults.slice(0, maxTasks).map((task) => ({
+            taskId: task.taskId,
+            baseline: compactRunResult(task.baseline),
+            antiGene: compactRunResult(task.antiGene),
+        })),
+        taskResultsTruncated: Math.max(0, report.taskResults.length - maxTasks),
+    };
+}
+function isReportPayload(value) {
+    return !!value && typeof value === 'object'
+        && typeof value.suite === 'string'
+        && typeof value.tasks === 'number'
+        && typeof value.verdict === 'string';
+}
+export function antiGeneRolloutReportsFromEvents(events) {
+    const out = [];
+    for (const event of events) {
+        if (event.type !== 'anti_gene.rollout_result')
+            continue;
+        if (isReportPayload(event.payload))
+            out.push(event.payload);
+    }
+    return out;
+}
+export function latestAntiGeneRolloutReport(events) {
+    const reports = antiGeneRolloutReportsFromEvents(events);
+    return reports[reports.length - 1] ?? null;
+}

package/dist/benchmark/benchmark.d.ts

@@ -0,0 +1,32 @@
+import type { Strategy } from '../strategy/strategyPoint.js';
+import { computeFitness, type FitnessSample, type FitnessScore, type FitnessWeights } from '../strategy/experiment.js';
+export interface BenchmarkCase<I> {
+    id: string;
+    input: I;
+}
+export interface BenchmarkSuite<I, O> {
+    name: string;
+    cases: ReadonlyArray<BenchmarkCase<I>>;
+    /** 评分: 给定 case 输入与策略输出, 产 fitness 样本(resolved/reuse/cost). */
+    score: (input: I, output: O, caseId: string) => FitnessSample;
+}
+export interface BenchmarkRunResult {
+    strategy: string;
+    version: string;
+    fitness: FitnessScore;
+}
+export interface BenchmarkReport {
+    suite: string;
+    results: BenchmarkRunResult[];
+    winner: string;
+}
+/**
+ * Benchmark 框架(M4-BM, D9). 对比进化算法各策略在同一题集上的 fitness, 排名选优.
+ * EverOS/SkillOpt 作**对照基线**(原创为主, 非复刻); 算法自进化时拿它当锚.
+ */
+export declare function runBenchmark<I, O>(suite: BenchmarkSuite<I, O>, strategies: ReadonlyArray<Strategy<I, O>>, weights?: FitnessWeights): Promise<BenchmarkReport>;
+/** EverOS 风格对照: 倾向复用既有 skill(reuse-first). 仅作比较锚, 非复刻. */
+export declare function everosControl<I, O>(run: (input: I) => O): Strategy<I, O>;
+/** SkillOpt 风格对照: 倾向优化单一最优 skill. 仅作比较锚, 非复刻. */
+export declare function skillOptControl<I, O>(run: (input: I) => O): Strategy<I, O>;
+export { computeFitness };

package/dist/benchmark/benchmark.js

@@ -0,0 +1,26 @@
+import { offlineReplay, computeFitness, DEFAULT_WEIGHTS } from '../strategy/experiment.js';
+/**
+ * Benchmark 框架(M4-BM, D9). 对比进化算法各策略在同一题集上的 fitness, 排名选优.
+ * EverOS/SkillOpt 作**对照基线**(原创为主, 非复刻); 算法自进化时拿它当锚.
+ */
+export async function runBenchmark(suite, strategies, weights = DEFAULT_WEIGHTS) {
+    const inputs = suite.cases.map((c) => c.input);
+    const ctxOf = (i) => ({ now: 0, cycleId: `bm-${suite.cases[i]?.id ?? i}` });
+    const results = [];
+    for (const s of strategies) {
+        const fitness = await offlineReplay(s, inputs, (input, output) => suite.score(input, output, ''), ctxOf, weights);
+        results.push({ strategy: s.name, version: s.version, fitness });
+    }
+    results.sort((a, b) => b.fitness.score - a.fitness.score);
+    return { suite: suite.name, results, winner: results[0]?.strategy ?? '' };
+}
+/* ── 对照基线(标注为 control, 不是真实现, D9) ── */
+/** EverOS 风格对照: 倾向复用既有 skill(reuse-first). 仅作比较锚, 非复刻. */
+export function everosControl(run) {
+    return { name: 'everos-control', version: 'baseline', run: (input) => run(input) };
+}
+/** SkillOpt 风格对照: 倾向优化单一最优 skill. 仅作比较锚, 非复刻. */
+export function skillOptControl(run) {
+    return { name: 'skillopt-control', version: 'baseline', run: (input) => run(input) };
+}
+export { computeFitness };

package/dist/benchmark/evolutionThesisSolver.d.ts

@@ -0,0 +1,25 @@
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import { type CycleInput, type CycleResult } from '../algo/cycleEngine.js';
+import { type RunCycleOptions } from '../algo/orchestrator.js';
+import type { ThesisArm, ThesisSolver, ThesisTask } from './thesis.js';
+export interface EvolutionThesisDeps<I> {
+    /** evolver arm store: the learned-gene pool (assembleCandidates pulls candidates from here). */
+    pool: AssetStoreProvider;
+    /** baseline arm store: no relevant genes, so the cycle innovates (no reuse). */
+    baseline: AssetStoreProvider;
+    /** Agent work; a deterministic fake in tests, makeSafeExecute(...) in prod. */
+    execute: CycleInput['execute'];
+    /** Map a thesis task to the cycle inputs (problem / signals / category / target / ...). */
+    toCycleOpts: (task: ThesisTask<I>) => Omit<RunCycleOptions, 'cycleId' | 'execute'>;
+    now?: () => number;
+    /** Event-log path per run (default: a fresh temp file per run). */
+    eventsPath?: (arm: ThesisArm, taskId: string) => string;
+    /** Normalized cost from the cycle result (default 1). */
+    cost?: (r: CycleResult) => number;
+}
+/**
+ * Build a ThesisSolver that drives the real CycleEngine + orchestrator. Feed the resulting solver to
+ * runThesis(). In production: pool = the gene pool, baseline = a fresh empty store, execute =
+ * makeSafeExecute(repo, store, safety, { validate }) so `passed` reflects an objective validation.
+ */
+export declare function makeEvolutionThesisSolver<I>(deps: EvolutionThesisDeps<I>): ThesisSolver<I>;

package/dist/benchmark/evolutionThesisSolver.js

@@ -0,0 +1,41 @@
+// Wire the honest thesis A/B harness to the REAL evolution loop. The evolver arm runs runEvolutionCycle
+// against the learned-gene pool (so selection can reuse a gene); the baseline arm runs against an empty
+// store (so it always innovates). Both use the same injected `execute` (a fake in tests; makeSafeExecute
+// in prod) and the same task. Objective outcome = the cycle reached 'solidified' (success, as decided by
+// the execute/validation hook); reuse = a gene was selected. Nothing about reuse feeds the pass/fail.
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Ingestor } from '../events/ingest.js';
+import { CycleEngine } from '../algo/cycleEngine.js';
+import { runEvolutionCycle } from '../algo/orchestrator.js';
+import { makeGeneSelectionPoint } from '../algo/geneSelection.js';
+/**
+ * Build a ThesisSolver that drives the real CycleEngine + orchestrator. Feed the resulting solver to
+ * runThesis(). In production: pool = the gene pool, baseline = a fresh empty store, execute =
+ * makeSafeExecute(repo, store, safety, { validate }) so `passed` reflects an objective validation.
+ */
+export function makeEvolutionThesisSolver(deps) {
+    const now = deps.now ?? (() => Date.now());
+    const eventsPath = deps.eventsPath
+        ?? ((arm, taskId) => join(mkdtempSync(join(tmpdir(), 'thesis-')), `${arm}-${taskId}.jsonl`));
+    return async (task, arm) => {
+        const store = arm === 'evolver' ? deps.pool : deps.baseline;
+        const engine = new CycleEngine({
+            ingestor: new Ingestor({ path: eventsPath(arm, task.id), now }),
+            selection: makeGeneSelectionPoint(),
+            store,
+            now,
+        });
+        const r = await runEvolutionCycle(engine, store, {
+            cycleId: `${arm}-${task.id}`,
+            ...deps.toCycleOpts(task),
+            execute: deps.execute,
+        });
+        return {
+            passed: r.finalStage === 'solidified', // success is decided by the execute/validation hook, not self-report
+            reusedGene: !!r.decision?.selectedGeneId,
+            cost: deps.cost ? deps.cost(r) : 1,
+        };
+    };
+}

package/dist/benchmark/index.d.ts

@@ -0,0 +1,5 @@
+export * from './benchmark.js';
+export * from './thesis.js';
+export * from './evolutionThesisSolver.js';
+export * from './antiGeneBenchmark.js';
+export * from './antiGeneRollout.js';

package/dist/benchmark/index.js

@@ -0,0 +1,5 @@
+export * from './benchmark.js';
+export * from './thesis.js';
+export * from './evolutionThesisSolver.js';
+export * from './antiGeneBenchmark.js';
+export * from './antiGeneRollout.js';

package/dist/benchmark/thesis.d.ts

@@ -0,0 +1,85 @@
+export type ThesisArm = 'baseline' | 'evolver';
+export interface ThesisTask<I> {
+    id: string;
+    input: I;
+}
+/** One task's objective result for one arm. */
+export interface ThesisOutcome {
+    /** Objectively solved (e.g. the validation hook passed). Decided by a verifier, not the agent. */
+    passed: boolean;
+    /** Normalized cost (tokens/time/etc.; caller defines the unit). */
+    cost: number;
+    /** Whether a prior gene was reused this run (descriptive only — never counted toward the verdict). */
+    reusedGene: boolean;
+}
+/**
+ * Solver seam: the real agent plugs in here (arm='evolver' runs with the learned-gene pool, 'baseline'
+ * runs without it). Tests inject a deterministic fake, so the harness is never bound to a live LLM.
+ */
+export type ThesisSolver<I> = (task: ThesisTask<I>, arm: ThesisArm) => Promise<ThesisOutcome> | ThesisOutcome;
+export interface ArmReport {
+    arm: ThesisArm;
+    n: number;
+    /** Tasks the arm objectively passed — the numerator behind passRate, kept so the verdict can run a real
+     *  two-proportion test (rates alone lose the counts the test needs). */
+    passes: number;
+    passRate: number;
+    avgCost: number;
+    /** Descriptive only, does not affect the verdict. baseline is ~0 (no gene pool). */
+    reuseRate: number;
+}
+export type ThesisVerdict = 'evolver_better' | 'no_significant_diff' | 'evolver_worse' | 'insufficient_samples';
+export interface ThesisReport {
+    suite: string;
+    baseline: ArmReport;
+    evolver: ArmReport;
+    /** evolver.passRate - baseline.passRate. The practical-significance input to the verdict. */
+    passRateDelta: number;
+    /** evolver.avgCost - baseline.avgCost. */
+    costDelta: number;
+    /** Two-proportion z statistic for (evolver − baseline) pass rates (pooled-variance test). 0 when undefined. */
+    z: number;
+    /** Two-sided p-value for `z` (normal approximation). 1 when the test is undefined (zero variance). */
+    pValue: number;
+    /** Whether the pass-rate difference is statistically significant at `alpha` (pValue <= alpha). A REQUIREMENT
+     *  for an evolver_better/worse verdict — a practical delta alone (>= minPassRateDelta) is no longer enough,
+     *  because at small n a 5pt delta is well inside sampling noise (the headline thesis number must be defensible). */
+    significant: boolean;
+    /** (1 − alpha) Wald confidence interval for passRateDelta. When it straddles 0 the difference is not significant. */
+    ciLow: number;
+    ciHigh: number;
+    /** Achieved power to detect an effect of size minPassRateDelta at the OBSERVED baseline rate and this n (alpha
+     *  two-sided). The number a bare `no_significant_diff` hides: a LOW power means the null is underpowered (the
+     *  experiment couldn't have seen the minimum interesting effect), not that there is no effect. 0 when undefined. */
+    power: number;
+    /** Per-arm sample size needed to reach `targetPower` for a minPassRateDelta effect at the observed baseline rate.
+     *  Actionable "run ~N tasks/arm" guidance; Infinity when minPassRateDelta is 0 (no effect size to power for). */
+    requiredN: number;
+    verdict: ThesisVerdict;
+}
+export interface ThesisOptions {
+    /** Min absolute passRate gain to call evolver better/worse (default 0.05) — the PRACTICAL bar. */
+    minPassRateDelta?: number;
+    /** Significance level for the two-proportion test (default 0.05) — the STATISTICAL bar. The verdict needs both. */
+    alpha?: number;
+    /** Min samples per arm before drawing a verdict (default 30); below it => insufficient_samples. */
+    minSamples?: number;
+    /** Target power for the requiredN guidance + the underpowered read of a null (default 0.8). */
+    targetPower?: number;
+    /**
+     * Interleave arms per task: run baseline then evolver on each task before moving to the next,
+     * instead of all-baseline first then all-evolver. Prevents API rate limits from hitting the
+     * second arm disproportionately (the serial default runs baseline entirely first, so evolver
+     * faces the tail-end of a rate-limit window).
+     */
+    interleave?: boolean;
+}
+/**
+ * Run both arms over the same task suite and compare. A verdict of evolver_better/worse requires BOTH a practical
+ * delta (|passRateDelta| >= minPassRateDelta) AND statistical significance (two-proportion test p <= alpha);
+ * otherwise no_significant_diff. reuseRate and costDelta are reported, never scored.
+ */
+export declare function runThesis<I>(suite: {
+    name: string;
+    tasks: readonly ThesisTask<I>[];
+}, solver: ThesisSolver<I>, opts?: ThesisOptions): Promise<ThesisReport>;