@tangle-network/agent-eval 0.144.11 → 0.144.13

package/dist/experiment-tracker-C29gXM4B.js

@@ -0,0 +1,269 @@
+import { s as ValidationError } from "./errors-Dngq5h35.js";
+import { n as iqr } from "./baseline-BhPRQBVn.js";
+import { execSync } from "node:child_process";
+//#region src/experiment-tracker.ts
+/**
+* Experiment tracker — git-provenanced experiment log with N-rep stats and a
+* KEEP / REGRESSION / NOISE verdict against a parent.
+*
+* Every loop the fleet runs reduces to the same question: "I ran the candidate
+* N times — is the median measurably better than the parent, or is the delta
+* inside the noise band?" The hand-rolled copies bake a fixed score scale
+* (percentage points), a fixed store path (`.evolve/experiments-v2.json`), and
+* `execSync('git …')` straight into the module. This is the canonical version:
+* provenance and persistence are injected, thresholds are configurable, and the
+* stats + verdict are pure functions you can unit-test without a git repo or a
+* filesystem.
+*
+* Stats per experiment: median / mean / min / max / iqr / stddev / passRate /
+* n, plus a `stable` flag (`iqr < iqrUnstableAbove && stddev < stddevUnstableAbove`).
+*
+* Verdict against a parent (both must have `n >= minRepsForVerdict`):
+*   - NOISE       — the candidate is too unstable to judge (`!stable`)
+*   - KEEP        — `medianDelta >  keepThreshold`
+*   - REGRESSION  — `medianDelta < -regressionThreshold`
+*   - NOISE       — otherwise (delta inside the band)
+* With no parent (or insufficient reps) the verdict is the neutral ITERATE.
+*/
+const DEFAULTS = {
+	keepThreshold: 5,
+	regressionThreshold: 5,
+	iqrUnstableAbove: 10,
+	stddevUnstableAbove: Number.POSITIVE_INFINITY,
+	minRepsForVerdict: 3
+};
+function resolveThresholds(t) {
+	const r = {
+		...DEFAULTS,
+		...t ?? {}
+	};
+	if (r.keepThreshold < 0) throw new ValidationError(`experiment-tracker: keepThreshold must be >= 0, got ${r.keepThreshold}`);
+	if (r.regressionThreshold < 0) throw new ValidationError(`experiment-tracker: regressionThreshold must be >= 0, got ${r.regressionThreshold}`);
+	if (r.minRepsForVerdict < 1) throw new ValidationError(`experiment-tracker: minRepsForVerdict must be >= 1, got ${r.minRepsForVerdict}`);
+	return r;
+}
+function median(sorted) {
+	const n = sorted.length;
+	if (n === 0) return 0;
+	const mid = Math.floor(n / 2);
+	return n % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/** Population standard deviation (÷n). 0 for fewer than 2 values. */
+function stddev(values, mean) {
+	if (values.length < 2) return 0;
+	const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / values.length;
+	return Math.sqrt(variance);
+}
+/**
+* Compute the N-rep statistics for a set of reps. Pure — no I/O. The `stable`
+* flag is the trust gate the verdict depends on: a sample whose spread exceeds
+* the configured bounds can't distinguish a real delta from run-to-run noise.
+*/
+function computeExperimentStats(reps, thresholds) {
+	const t = resolveThresholds(thresholds);
+	const n = reps.length;
+	if (n === 0) return {
+		median: 0,
+		mean: 0,
+		min: 0,
+		max: 0,
+		iqr: 0,
+		stddev: 0,
+		passRate: null,
+		n: 0,
+		stable: false
+	};
+	const scores = reps.map((r) => {
+		if (!Number.isFinite(r.score)) throw new ValidationError(`experiment-tracker: rep ${r.rep} has non-finite score ${r.score}`);
+		return r.score;
+	});
+	const sorted = [...scores].sort((a, b) => a - b);
+	const mean = scores.reduce((s, v) => s + v, 0) / n;
+	const sd = stddev(scores, mean);
+	const spread = iqr(scores);
+	const rated = reps.filter((r) => typeof r.passed === "boolean");
+	const passRate = rated.length === 0 ? null : rated.filter((r) => r.passed).length / rated.length;
+	const stable = spread < t.iqrUnstableAbove && sd < t.stddevUnstableAbove;
+	return {
+		median: median(sorted),
+		mean,
+		min: sorted[0],
+		max: sorted[n - 1],
+		iqr: spread,
+		stddev: sd,
+		passRate,
+		n,
+		stable
+	};
+}
+/**
+* Verdict for a candidate against its parent. Pure — operates on already-computed
+* stats. KEEP/REGRESSION require both sides to have `>= minRepsForVerdict` reps
+* AND the candidate to be `stable`; otherwise the result is NOISE (unstable) or
+* ITERATE (not enough reps / no parent).
+*/
+function improvementVerdict(candidate, parent, thresholds) {
+	const t = resolveThresholds(thresholds);
+	if (!parent) return {
+		verdict: "ITERATE",
+		medianDelta: null,
+		reason: "no parent experiment to compare against"
+	};
+	if (candidate.n < t.minRepsForVerdict || parent.n < t.minRepsForVerdict) return {
+		verdict: "ITERATE",
+		medianDelta: null,
+		reason: `need >= ${t.minRepsForVerdict} reps on both sides (candidate n=${candidate.n}, parent n=${parent.n})`
+	};
+	if (!candidate.stable) return {
+		verdict: "NOISE",
+		medianDelta: candidate.median - parent.median,
+		reason: `candidate unstable (iqr=${candidate.iqr}, stddev=${candidate.stddev.toFixed(2)})`
+	};
+	const medianDelta = candidate.median - parent.median;
+	if (medianDelta > t.keepThreshold) return {
+		verdict: "KEEP",
+		medianDelta,
+		reason: `median +${medianDelta} > +${t.keepThreshold}`
+	};
+	if (medianDelta < -t.regressionThreshold) return {
+		verdict: "REGRESSION",
+		medianDelta,
+		reason: `median ${medianDelta} < -${t.regressionThreshold}`
+	};
+	return {
+		verdict: "NOISE",
+		medianDelta,
+		reason: `median delta ${medianDelta} inside noise band [-${t.regressionThreshold}, +${t.keepThreshold}]`
+	};
+}
+/**
+* Default provenance reader: `git rev-parse HEAD`, the subject line, and the
+* files changed vs `HEAD~1`. Fail-loud — a tracker that silently logs
+* `commit: 'unknown'` corrupts the provenance the whole point of the log is to
+* carry. When the working tree genuinely has no parent commit, pass an override.
+*/
+const gitProvenanceReader = () => {
+	const run = (cmd) => execSync(cmd, { encoding: "utf8" }).trim();
+	const commit = run("git rev-parse --short HEAD");
+	const message = run("git log -1 --format=%s");
+	const changedRaw = run("git diff --name-only HEAD~1");
+	return {
+		commit,
+		message,
+		changedFiles: changedRaw.length === 0 ? [] : changedRaw.split("\n").filter(Boolean)
+	};
+};
+/** In-memory store — the default when no persistence is wanted (tests, ephemeral
+*  runs). State lives on the instance. */
+function inMemoryExperimentStore(initial = []) {
+	let state = initial.map((e) => structuredClone(e));
+	return {
+		async load() {
+			return state.map((e) => structuredClone(e));
+		},
+		async save(experiments) {
+			state = experiments.map((e) => structuredClone(e));
+		}
+	};
+}
+/** Filesystem store — a single JSON array at `path`, created on first save. */
+function fileExperimentStore(path) {
+	return {
+		async load() {
+			const fs = await import("node:fs/promises");
+			try {
+				const raw = await fs.readFile(path, "utf8");
+				const parsed = JSON.parse(raw);
+				if (!Array.isArray(parsed)) throw new ValidationError(`experiment-tracker: store at ${path} is not a JSON array`);
+				return parsed;
+			} catch (err) {
+				if (err.code === "ENOENT") return [];
+				throw err;
+			}
+		},
+		async save(experiments) {
+			const fs = await import("node:fs/promises");
+			const pathMod = await import("node:path");
+			await fs.mkdir(pathMod.dirname(path), { recursive: true });
+			await fs.writeFile(path, JSON.stringify(experiments, null, 2), "utf8");
+		}
+	};
+}
+/**
+* Stateful tracker over an `ExperimentStore`. Create an experiment (provenance
+* is captured once), append reps as they complete (stats + verdict recompute on
+* every append), and read the log back for a dashboard. All persistence and git
+* access flow through the injected seams, so the tracker is fully testable
+* without a repo or disk.
+*/
+var ExperimentTracker = class {
+	store;
+	provenanceReader;
+	thresholds;
+	now;
+	constructor(options = {}) {
+		this.store = options.store ?? inMemoryExperimentStore();
+		this.provenanceReader = options.provenanceReader ?? gitProvenanceReader;
+		this.thresholds = resolveThresholds(options.thresholds);
+		this.now = options.now ?? Date.now;
+	}
+	async create(input) {
+		const experiments = await this.store.load();
+		if (experiments.some((e) => e.id === input.id)) throw new ValidationError(`experiment-tracker: experiment id "${input.id}" already exists`);
+		if (input.parentId && !experiments.some((e) => e.id === input.parentId)) throw new ValidationError(`experiment-tracker: parent experiment "${input.parentId}" not found`);
+		const provenance = input.provenance ?? await this.provenanceReader();
+		const experiment = {
+			id: input.id,
+			label: input.label,
+			provenance,
+			parentId: input.parentId,
+			changeSummary: input.changeSummary,
+			reps: [],
+			stats: computeExperimentStats([], this.thresholds),
+			verdict: "ITERATE",
+			createdAt: new Date(this.now()).toISOString()
+		};
+		experiments.push(experiment);
+		await this.store.save(experiments);
+		return structuredClone(experiment);
+	}
+	/** Append a rep (its `rep` index defaults to the current rep count) and
+	*  recompute stats + verdict. Returns the updated experiment. */
+	async addRep(experimentId, rep) {
+		const experiments = await this.store.load();
+		const exp = experiments.find((e) => e.id === experimentId);
+		if (!exp) throw new ValidationError(`experiment-tracker: experiment "${experimentId}" not found`);
+		const fullRep = {
+			rep: rep.rep ?? exp.reps.length,
+			score: rep.score,
+			passed: rep.passed,
+			metrics: rep.metrics,
+			timestamp: rep.timestamp ?? new Date(this.now()).toISOString()
+		};
+		exp.reps.push(fullRep);
+		exp.stats = computeExperimentStats(exp.reps, this.thresholds);
+		const parent = exp.parentId ? experiments.find((e) => e.id === exp.parentId) : void 0;
+		exp.verdict = improvementVerdict(exp.stats, parent?.stats ?? null, this.thresholds).verdict;
+		await this.store.save(experiments);
+		return structuredClone(exp);
+	}
+	async get(experimentId) {
+		const found = (await this.store.load()).find((e) => e.id === experimentId);
+		return found ? structuredClone(found) : void 0;
+	}
+	async list() {
+		return this.store.load();
+	}
+	/** Full verdict (not just the enum) for an experiment vs its parent. */
+	async verdictFor(experimentId) {
+		const experiments = await this.store.load();
+		const exp = experiments.find((e) => e.id === experimentId);
+		if (!exp) throw new ValidationError(`experiment-tracker: experiment "${experimentId}" not found`);
+		const parent = exp.parentId ? experiments.find((e) => e.id === exp.parentId) : void 0;
+		return improvementVerdict(exp.stats, parent?.stats ?? null, this.thresholds);
+	}
+};
+//#endregion
+export { inMemoryExperimentStore as a, improvementVerdict as i, computeExperimentStats as n, fileExperimentStore as r, ExperimentTracker as t };
+
+//# sourceMappingURL=experiment-tracker-C29gXM4B.js.map

package/dist/experiment-tracker-C29gXM4B.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment-tracker-C29gXM4B.js","names":[],"sources":["../src/experiment-tracker.ts"],"sourcesContent":["/**\n * Experiment tracker — git-provenanced experiment log with N-rep stats and a\n * KEEP / REGRESSION / NOISE verdict against a parent.\n *\n * Every loop the fleet runs reduces to the same question: \"I ran the candidate\n * N times — is the median measurably better than the parent, or is the delta\n * inside the noise band?\" The hand-rolled copies bake a fixed score scale\n * (percentage points), a fixed store path (`.evolve/experiments-v2.json`), and\n * `execSync('git …')` straight into the module. This is the canonical version:\n * provenance and persistence are injected, thresholds are configurable, and the\n * stats + verdict are pure functions you can unit-test without a git repo or a\n * filesystem.\n *\n * Stats per experiment: median / mean / min / max / iqr / stddev / passRate /\n * n, plus a `stable` flag (`iqr < iqrUnstableAbove && stddev < stddevUnstableAbove`).\n *\n * Verdict against a parent (both must have `n >= minRepsForVerdict`):\n *   - NOISE       — the candidate is too unstable to judge (`!stable`)\n *   - KEEP        — `medianDelta >  keepThreshold`\n *   - REGRESSION  — `medianDelta < -regressionThreshold`\n *   - NOISE       — otherwise (delta inside the band)\n * With no parent (or insufficient reps) the verdict is the neutral ITERATE.\n */\n\nimport { execSync } from 'node:child_process'\nimport { iqr } from './baseline'\nimport { ValidationError } from './errors'\n\n/** Verdict for one experiment relative to its parent. ITERATE is the neutral\n *  \"keep collecting reps / no parent to compare against\" state. */\nexport type ExperimentVerdict = 'KEEP' | 'ITERATE' | 'NOISE' | 'REGRESSION'\n\n/** Git provenance for the working tree an experiment was run from. */\nexport interface ExperimentProvenance {\n  /** Commit sha (short or full — the tracker does not interpret it). */\n  commit: string\n  /** First line of the commit message. */\n  message: string\n  /** Files changed vs the parent commit, or a marker like 'uncommitted'. */\n  changedFiles: string[]\n}\n\n/** A single repetition of an experiment, carrying the score the verdict is\n *  computed on plus any free-form per-rep metrics the consumer wants kept. */\nexport interface ExperimentRep {\n  /** 0-indexed repetition number within the experiment. */\n  rep: number\n  /** The score this rep is judged on (same scale as the thresholds). */\n  score: number\n  /** ISO timestamp the rep completed. */\n  timestamp: string\n  /** Whether this rep passed the consumer's own gate — folded into `passRate`. */\n  passed?: boolean\n  /** Free-form numeric metrics retained for later analysis. */\n  metrics?: Record<string, number>\n}\n\nexport interface ExperimentStats {\n  median: number\n  mean: number\n  min: number\n  max: number\n  /** Inter-quartile range of the rep scores. */\n  iqr: number\n  /** Population standard deviation of the rep scores. */\n  stddev: number\n  /** Fraction of reps with `passed === true`, over reps that set `passed`.\n   *  null when no rep declared a pass/fail outcome. */\n  passRate: number | null\n  /** Number of reps. */\n  n: number\n  /** True when the sample is tight enough to trust for a verdict. */\n  stable: boolean\n}\n\nexport interface Experiment {\n  /** Stable id for the experiment. */\n  id: string\n  /** Free-form label / config descriptor. */\n  label: string\n  /** Git provenance captured when the experiment was created. */\n  provenance: ExperimentProvenance\n  /** Parent experiment id this candidate is compared against, if any. */\n  parentId?: string\n  /** One-line summary of what changed from the parent. */\n  changeSummary: string\n  reps: ExperimentRep[]\n  stats: ExperimentStats\n  verdict: ExperimentVerdict\n  /** ISO timestamp the experiment was created. */\n  createdAt: string\n}\n\nexport interface ImprovementThresholds {\n  /** medianDelta strictly above this ⇒ KEEP. Default 5. */\n  keepThreshold?: number\n  /** medianDelta strictly below the negative of this ⇒ REGRESSION. Default 5. */\n  regressionThreshold?: number\n  /** iqr at or above this ⇒ unstable. Default 10. */\n  iqrUnstableAbove?: number\n  /** stddev at or above this ⇒ unstable. Default Infinity (iqr-only stability). */\n  stddevUnstableAbove?: number\n  /** Reps required on BOTH candidate and parent before a verdict is rendered.\n   *  Default 3. */\n  minRepsForVerdict?: number\n}\n\nexport interface ImprovementVerdictResult {\n  verdict: ExperimentVerdict\n  /** candidate.median − parent.median; null when no parent or insufficient reps. */\n  medianDelta: number | null\n  /** Human-readable reason for the verdict — for dashboards and logs. */\n  reason: string\n}\n\nconst DEFAULTS: Required<ImprovementThresholds> = {\n  keepThreshold: 5,\n  regressionThreshold: 5,\n  iqrUnstableAbove: 10,\n  stddevUnstableAbove: Number.POSITIVE_INFINITY,\n  minRepsForVerdict: 3,\n}\n\nfunction resolveThresholds(t: ImprovementThresholds | undefined): Required<ImprovementThresholds> {\n  const r = { ...DEFAULTS, ...(t ?? {}) }\n  if (r.keepThreshold < 0) {\n    throw new ValidationError(\n      `experiment-tracker: keepThreshold must be >= 0, got ${r.keepThreshold}`,\n    )\n  }\n  if (r.regressionThreshold < 0) {\n    throw new ValidationError(\n      `experiment-tracker: regressionThreshold must be >= 0, got ${r.regressionThreshold}`,\n    )\n  }\n  if (r.minRepsForVerdict < 1) {\n    throw new ValidationError(\n      `experiment-tracker: minRepsForVerdict must be >= 1, got ${r.minRepsForVerdict}`,\n    )\n  }\n  return r\n}\n\nfunction median(sorted: number[]): number {\n  const n = sorted.length\n  if (n === 0) return 0\n  const mid = Math.floor(n / 2)\n  return n % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!\n}\n\n/** Population standard deviation (÷n). 0 for fewer than 2 values. */\nfunction stddev(values: number[], mean: number): number {\n  if (values.length < 2) return 0\n  const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / values.length\n  return Math.sqrt(variance)\n}\n\n/**\n * Compute the N-rep statistics for a set of reps. Pure — no I/O. The `stable`\n * flag is the trust gate the verdict depends on: a sample whose spread exceeds\n * the configured bounds can't distinguish a real delta from run-to-run noise.\n */\nexport function computeExperimentStats(\n  reps: ExperimentRep[],\n  thresholds?: ImprovementThresholds,\n): ExperimentStats {\n  const t = resolveThresholds(thresholds)\n  const n = reps.length\n  if (n === 0) {\n    return {\n      median: 0,\n      mean: 0,\n      min: 0,\n      max: 0,\n      iqr: 0,\n      stddev: 0,\n      passRate: null,\n      n: 0,\n      stable: false,\n    }\n  }\n  const scores = reps.map((r) => {\n    if (!Number.isFinite(r.score)) {\n      throw new ValidationError(`experiment-tracker: rep ${r.rep} has non-finite score ${r.score}`)\n    }\n    return r.score\n  })\n  const sorted = [...scores].sort((a, b) => a - b)\n  const mean = scores.reduce((s, v) => s + v, 0) / n\n  const sd = stddev(scores, mean)\n  const spread = iqr(scores)\n  const rated = reps.filter((r) => typeof r.passed === 'boolean')\n  const passRate = rated.length === 0 ? null : rated.filter((r) => r.passed).length / rated.length\n  const stable = spread < t.iqrUnstableAbove && sd < t.stddevUnstableAbove\n  return {\n    median: median(sorted),\n    mean,\n    min: sorted[0]!,\n    max: sorted[n - 1]!,\n    iqr: spread,\n    stddev: sd,\n    passRate,\n    n,\n    stable,\n  }\n}\n\n/**\n * Verdict for a candidate against its parent. Pure — operates on already-computed\n * stats. KEEP/REGRESSION require both sides to have `>= minRepsForVerdict` reps\n * AND the candidate to be `stable`; otherwise the result is NOISE (unstable) or\n * ITERATE (not enough reps / no parent).\n */\nexport function improvementVerdict(\n  candidate: ExperimentStats,\n  parent: ExperimentStats | null,\n  thresholds?: ImprovementThresholds,\n): ImprovementVerdictResult {\n  const t = resolveThresholds(thresholds)\n  if (!parent) {\n    return {\n      verdict: 'ITERATE',\n      medianDelta: null,\n      reason: 'no parent experiment to compare against',\n    }\n  }\n  if (candidate.n < t.minRepsForVerdict || parent.n < t.minRepsForVerdict) {\n    return {\n      verdict: 'ITERATE',\n      medianDelta: null,\n      reason: `need >= ${t.minRepsForVerdict} reps on both sides (candidate n=${candidate.n}, parent n=${parent.n})`,\n    }\n  }\n  if (!candidate.stable) {\n    return {\n      verdict: 'NOISE',\n      medianDelta: candidate.median - parent.median,\n      reason: `candidate unstable (iqr=${candidate.iqr}, stddev=${candidate.stddev.toFixed(2)})`,\n    }\n  }\n  const medianDelta = candidate.median - parent.median\n  if (medianDelta > t.keepThreshold) {\n    return { verdict: 'KEEP', medianDelta, reason: `median +${medianDelta} > +${t.keepThreshold}` }\n  }\n  if (medianDelta < -t.regressionThreshold) {\n    return {\n      verdict: 'REGRESSION',\n      medianDelta,\n      reason: `median ${medianDelta} < -${t.regressionThreshold}`,\n    }\n  }\n  return {\n    verdict: 'NOISE',\n    medianDelta,\n    reason: `median delta ${medianDelta} inside noise band [-${t.regressionThreshold}, +${t.keepThreshold}]`,\n  }\n}\n\n// ── Provenance + persistence seams ───────────────────────────────────\n\n/** Reads git provenance for the working tree. Inject a fake in tests; the\n *  default implementation shells out to `git`. */\nexport type ProvenanceReader = () => ExperimentProvenance | Promise<ExperimentProvenance>\n\n/** Persistence seam for the experiment log. Inject in-memory in tests; the\n *  filesystem implementation is `fileExperimentStore`. */\nexport interface ExperimentStore {\n  load(): Promise<Experiment[]>\n  save(experiments: Experiment[]): Promise<void>\n}\n\n/**\n * Default provenance reader: `git rev-parse HEAD`, the subject line, and the\n * files changed vs `HEAD~1`. Fail-loud — a tracker that silently logs\n * `commit: 'unknown'` corrupts the provenance the whole point of the log is to\n * carry. When the working tree genuinely has no parent commit, pass an override.\n */\nexport const gitProvenanceReader: ProvenanceReader = () => {\n  const run = (cmd: string): string => execSync(cmd, { encoding: 'utf8' }).trim()\n  const commit = run('git rev-parse --short HEAD')\n  const message = run('git log -1 --format=%s')\n  const changedRaw = run('git diff --name-only HEAD~1')\n  const changedFiles = changedRaw.length === 0 ? [] : changedRaw.split('\\n').filter(Boolean)\n  return { commit, message, changedFiles }\n}\n\n/** In-memory store — the default when no persistence is wanted (tests, ephemeral\n *  runs). State lives on the instance. */\nexport function inMemoryExperimentStore(initial: Experiment[] = []): ExperimentStore {\n  let state = initial.map((e) => structuredClone(e))\n  return {\n    async load() {\n      return state.map((e) => structuredClone(e))\n    },\n    async save(experiments) {\n      state = experiments.map((e) => structuredClone(e))\n    },\n  }\n}\n\n/** Filesystem store — a single JSON array at `path`, created on first save. */\nexport function fileExperimentStore(path: string): ExperimentStore {\n  return {\n    async load() {\n      const fs = await import('node:fs/promises')\n      try {\n        const raw = await fs.readFile(path, 'utf8')\n        const parsed = JSON.parse(raw)\n        if (!Array.isArray(parsed)) {\n          throw new ValidationError(`experiment-tracker: store at ${path} is not a JSON array`)\n        }\n        return parsed as Experiment[]\n      } catch (err) {\n        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []\n        throw err\n      }\n    },\n    async save(experiments) {\n      const fs = await import('node:fs/promises')\n      const pathMod = await import('node:path')\n      await fs.mkdir(pathMod.dirname(path), { recursive: true })\n      await fs.writeFile(path, JSON.stringify(experiments, null, 2), 'utf8')\n    },\n  }\n}\n\nexport interface ExperimentTrackerOptions {\n  store?: ExperimentStore\n  provenanceReader?: ProvenanceReader\n  thresholds?: ImprovementThresholds\n  /** Clock seam for deterministic timestamps in tests. Default `Date.now`. */\n  now?: () => number\n}\n\nexport interface CreateExperimentInput {\n  id: string\n  label: string\n  changeSummary: string\n  parentId?: string\n  /** Override provenance instead of reading from git (e.g. CI metadata). */\n  provenance?: ExperimentProvenance\n}\n\n/**\n * Stateful tracker over an `ExperimentStore`. Create an experiment (provenance\n * is captured once), append reps as they complete (stats + verdict recompute on\n * every append), and read the log back for a dashboard. All persistence and git\n * access flow through the injected seams, so the tracker is fully testable\n * without a repo or disk.\n */\nexport class ExperimentTracker {\n  private readonly store: ExperimentStore\n  private readonly provenanceReader: ProvenanceReader\n  private readonly thresholds: Required<ImprovementThresholds>\n  private readonly now: () => number\n\n  constructor(options: ExperimentTrackerOptions = {}) {\n    this.store = options.store ?? inMemoryExperimentStore()\n    this.provenanceReader = options.provenanceReader ?? gitProvenanceReader\n    this.thresholds = resolveThresholds(options.thresholds)\n    this.now = options.now ?? Date.now\n  }\n\n  async create(input: CreateExperimentInput): Promise<Experiment> {\n    const experiments = await this.store.load()\n    if (experiments.some((e) => e.id === input.id)) {\n      throw new ValidationError(`experiment-tracker: experiment id \"${input.id}\" already exists`)\n    }\n    if (input.parentId && !experiments.some((e) => e.id === input.parentId)) {\n      throw new ValidationError(\n        `experiment-tracker: parent experiment \"${input.parentId}\" not found`,\n      )\n    }\n    const provenance = input.provenance ?? (await this.provenanceReader())\n    const experiment: Experiment = {\n      id: input.id,\n      label: input.label,\n      provenance,\n      parentId: input.parentId,\n      changeSummary: input.changeSummary,\n      reps: [],\n      stats: computeExperimentStats([], this.thresholds),\n      verdict: 'ITERATE',\n      createdAt: new Date(this.now()).toISOString(),\n    }\n    experiments.push(experiment)\n    await this.store.save(experiments)\n    return structuredClone(experiment)\n  }\n\n  /** Append a rep (its `rep` index defaults to the current rep count) and\n   *  recompute stats + verdict. Returns the updated experiment. */\n  async addRep(\n    experimentId: string,\n    rep: Omit<ExperimentRep, 'rep' | 'timestamp'> & { rep?: number; timestamp?: string },\n  ): Promise<Experiment> {\n    const experiments = await this.store.load()\n    const exp = experiments.find((e) => e.id === experimentId)\n    if (!exp)\n      throw new ValidationError(`experiment-tracker: experiment \"${experimentId}\" not found`)\n    const fullRep: ExperimentRep = {\n      rep: rep.rep ?? exp.reps.length,\n      score: rep.score,\n      passed: rep.passed,\n      metrics: rep.metrics,\n      timestamp: rep.timestamp ?? new Date(this.now()).toISOString(),\n    }\n    exp.reps.push(fullRep)\n    exp.stats = computeExperimentStats(exp.reps, this.thresholds)\n    const parent = exp.parentId ? experiments.find((e) => e.id === exp.parentId) : undefined\n    exp.verdict = improvementVerdict(exp.stats, parent?.stats ?? null, this.thresholds).verdict\n    await this.store.save(experiments)\n    return structuredClone(exp)\n  }\n\n  async get(experimentId: string): Promise<Experiment | undefined> {\n    const experiments = await this.store.load()\n    const found = experiments.find((e) => e.id === experimentId)\n    return found ? structuredClone(found) : undefined\n  }\n\n  async list(): Promise<Experiment[]> {\n    return this.store.load()\n  }\n\n  /** Full verdict (not just the enum) for an experiment vs its parent. */\n  async verdictFor(experimentId: string): Promise<ImprovementVerdictResult> {\n    const experiments = await this.store.load()\n    const exp = experiments.find((e) => e.id === experimentId)\n    if (!exp)\n      throw new ValidationError(`experiment-tracker: experiment \"${experimentId}\" not found`)\n    const parent = exp.parentId ? experiments.find((e) => e.id === exp.parentId) : undefined\n    return improvementVerdict(exp.stats, parent?.stats ?? null, this.thresholds)\n  }\n}\n"],"mappings":"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"}

package/dist/{experiment-tracker-IMntXr6J.d.ts → experiment-tracker-DWHZBAYL.d.ts}

@@ -1,120 +1,83 @@
-//#region src/clustered-paired-binary.d.ts
+//#region src/statistics/power-and-mde.d.ts
 /**
- * Paired binary comparison for work items nested inside independent clusters.
+ * Required N per arm for a two-sample comparison at target effect size,
+ * alpha, and power. Normal-approximation formula:
+ *   n = 2 * ( (z_{1-α/2} + z_{1-β}) / d )^2
+ * where d is Cohen's d. Returns Infinity for effect ≤ 0.
+ */
+declare function requiredSampleSize(opts: {
+  effect: number;
+  alpha?: number;
+  power?: number;
+  twoSided?: boolean;
+}): number;
+/**
+ * Required number of paired observations for a target Cohen's dz.
+ * Unlike the independent-groups formula, this has no two-arm factor of two.
  *
- * Pairing is delegated to {@link pairArms}; this module adds the cluster-aware
- * estimands and inference that task-level McNemar/bootstrap utilities cannot
- * provide. Callers keep their own row shape through accessors, and every
- * matched or unpaired result returns the original row object unchanged.
+ * Normal quantiles with no t correction, so treat the result as a LOWER bound:
+ * it returns 32 where the exact t-based answer is 34 at dz = 0.5, and 13 where
+ * it is 15 at dz = 0.8 — a 6–13 % shortfall precisely in the range a caller
+ * consults to decide whether 3–10 repetitions suffice.
  */
-type ClusterSignFlipAlternative = 'two-sided' | 'greater' | 'less';
-interface ClusteredPairedBinaryOptions<TRow> {
-  /** Arm treated as the control side of every pair. */
-  baselineArm: string;
-  /** Arm treated as the treatment side of every pair. */
-  treatmentArm: string;
-  /** Stable work-item identity shared by both arms. */
-  pairKey: (row: TRow) => string;
-  /** Independent-cluster identity, shared by both rows in a matched pair. */
-  clusterKey: (row: TRow) => string;
-  /** Arm identity for this row. Rows from other arms are ignored. */
-  arm: (row: TRow) => string;
-  /** Binary outcome. */
-  pass: (row: TRow) => boolean;
-  /** Replicate identity when a work item has multiple rows in either arm. */
-  repKey?: (row: TRow) => string | undefined;
-  /** Deterministic seed for bootstrap and Monte Carlo sign-flip draws. */
-  seed: number;
-  /** Percentile confidence level. Default 0.95. */
-  confidence?: number;
-  /** Whole-cluster bootstrap draws. Default 10,000; maximum 1,000,000. */
-  bootstrapResamples?: number;
-  /** Sign-flip alternative. Default 'two-sided'. */
-  alternative?: ClusterSignFlipAlternative;
-  /**
-   * Enumerate every sign assignment at or below this many non-zero clusters;
-   * otherwise use Monte Carlo. Default 20; maximum 20.
-   */
-  exactClusterLimit?: number;
-  /** Monte Carlo sign-flip draws when exact enumeration is not used. Default 100,000; maximum 1,000,000. */
-  signFlipResamples?: number;
-}
-interface ClusteredMatchedPair<TRow> {
-  pairKey: string;
-  repIndex: number;
-  clusterKey: string;
-  baseline: TRow;
-  treatment: TRow;
-  baselinePass: boolean;
-  treatmentPass: boolean;
-}
-interface ClusteredBinaryCluster {
-  clusterKey: string;
-  nPairs: number;
-  /** Treatment passes and baseline fails. */
-  b10: number;
-  /** Baseline passes and treatment fails. */
-  b01: number;
-  /** Mean (treatment - baseline) binary outcome within this cluster. */
-  meanDifference: number;
-}
-interface ClusterBootstrapInterval {
-  /** The interval resamples clusters and recomputes this task-weighted statistic. */
-  statistic: 'task-weighted-risk-difference';
-  lower: number;
-  upper: number;
-  confidence: number;
-  resamples: number;
-  seed: number;
-}
-interface ClusterSignFlipResult {
-  /** Task-weighted paired risk difference, matching the reported bootstrap estimand. */
-  statistic: number;
-  /**
-   * Randomization p-value under whole-cluster arm-label exchangeability.
-   * `method: 'exact'` means every cluster-level sign assignment was enumerated;
-   * it does not make the exchangeability assumption unnecessary.
-   */
-  pValue: number;
-  alternative: ClusterSignFlipAlternative;
-  method: 'exact' | 'monte-carlo';
-  /** Exact assignments enumerated or Monte Carlo assignments drawn. */
-  assignments: number;
-  nClusters: number;
-  nNonZeroClusters: number;
-  /** Null for exact enumeration, which has no random draws. */
-  seed: number | null;
-}
-interface ClusteredPairedBinaryStatistics {
-  nPairs: number;
-  nClusters: number;
-  /** Treatment passes and baseline fails, across all matched pairs. */
-  b10: number;
-  /** Baseline passes and treatment fails, across all matched pairs. */
-  b01: number;
-  /** Mean paired difference across tasks, so every task has equal weight. */
-  taskWeightedRiskDifference: number;
-  /** Mean of cluster-level paired differences, so every cluster has equal weight. */
-  equalClusterMean: number;
-  clusters: ClusteredBinaryCluster[];
-  /** Null below two independent clusters; one cluster cannot estimate cluster uncertainty. */
-  bootstrap: ClusterBootstrapInterval | null;
-  signFlip: ClusterSignFlipResult;
-}
-interface ClusteredPairedBinaryResult<TRow> {
-  matchedPairs: ClusteredMatchedPair<TRow>[];
-  unpairedBaseline: TRow[];
-  unpairedTreatment: TRow[];
-  /** Null when there are no matched rows; absence is never reported as a zero effect. */
-  statistics: ClusteredPairedBinaryStatistics | null;
-}
+declare function requiredPairedSampleSize(opts: {
+  effect: number;
+  alpha?: number;
+  power?: number;
+  twoSided?: boolean;
+}): number;
+/**
+ * Minimum detectable paired effect (standardised units) for a target paired
+ * sample size: d_min = (z_{1-α/2} + z_β) / sqrt(n_paired). Multiply by
+ * sd(deltas) for score units; treat as a lower bound — Wilcoxon and bootstrap
+ * have asymptotic relative efficiency below 1 vs the t-test on heavy tails.
+ */
+declare function pairedMde(opts: {
+  nPaired: number;
+  alpha?: number;
+  power?: number;
+  twoSided?: boolean;
+}): number;
+/**
+ * Number of paired observations needed for a McNemar test to reach a target
+ * power — the pre-registration companion to {@link mcnemar}. Parametrised by the
+ * expected discordant-cell probabilities `p10` (P[treatment wins on a pair]) and
+ * `p01` (P[control wins]); concordant pairs carry no information, so the count
+ * is driven entirely by the discordant rate. Lachin's (1992) asymptotic normal
+ * approximation: with discordant rate `pDisc = p10 + p01` and marginal effect
+ * `δ = p10 − p01`,
+ *   n = ( z_{1-α/2}·√pDisc + z_{1-β}·√(pDisc − δ²) )² / δ².
+ * Returns Infinity when there is no effect (p10 === p01). Asymptotic — at the
+ * tiny discordant counts where the exact {@link mcnemar} differs from the normal
+ * approximation, treat the result as a lower bound and prefer the discordant-pair
+ * floor.
+ */
+declare function mcnemarRequiredN(opts: {
+  p10: number;
+  p01: number;
+  alpha?: number;
+  power?: number;
+  twoSided?: boolean;
+}): number;
 /**
- * Compare binary outcomes on matched work items while respecting independent
- * clusters. The confidence interval resamples whole clusters and recomputes the
- * task-weighted risk difference. The sign-flip test flips whole-cluster outcome
- * totals and tests that same task-weighted estimand.
+ * Power of a McNemar test at a given number of paired observations, the inverse
+ * of {@link mcnemarRequiredN} (same Lachin asymptotic model, same parameters).
+ * Returns a value in [0, 1]; equals `alpha` when there is no effect.
  */
-declare function clusteredPairedBinary<TRow>(rows: readonly TRow[], options: ClusteredPairedBinaryOptions<TRow>): ClusteredPairedBinaryResult<TRow>;
+declare function mcnemarPower(opts: {
+  p10: number;
+  p01: number;
+  nPairs: number;
+  alpha?: number;
+  twoSided?: boolean;
+}): number;
+//#endregion
+//#region src/statistics/random.d.ts
+/** Tiny seedable PRNG (mulberry32) — deterministic resampling/shuffling, not
+ *  cryptographic. Exported so e-process shuffles and bootstrap resampling
+ *  share ONE PRNG implementation. Every distinct 32-bit seed gives a distinct
+ *  stream, including 0. */
+declare function mulberry32(seed: number): () => number;
 //#endregion
 //#region src/experiment-tracker.d.ts
 /**
@@ -242,13 +205,6 @@ interface ExperimentStore {
   load(): Promise<Experiment[]>;
   save(experiments: Experiment[]): Promise<void>;
 }
-/**
- * Default provenance reader: `git rev-parse HEAD`, the subject line, and the
- * files changed vs `HEAD~1`. Fail-loud — a tracker that silently logs
- * `commit: 'unknown'` corrupts the provenance the whole point of the log is to
- * carry. When the working tree genuinely has no parent commit, pass an override.
- */
-declare const gitProvenanceReader: ProvenanceReader;
 /** In-memory store — the default when no persistence is wanted (tests, ephemeral
  *  runs). State lives on the instance. */
 declare function inMemoryExperimentStore(initial?: Experiment[]): ExperimentStore;
@@ -295,5 +251,5 @@ declare class ExperimentTracker {
   verdictFor(experimentId: string): Promise<ImprovementVerdictResult>;
 }
 //#endregion
-export { ClusteredPairedBinaryOptions as C, clusteredPairedBinary as E, ClusteredMatchedPair as S, ClusteredPairedBinaryStatistics as T, inMemoryExperimentStore as _, ExperimentStats as a, ClusterSignFlipResult as b, ExperimentTrackerOptions as c, ImprovementVerdictResult as d, ProvenanceReader as f, improvementVerdict as g, gitProvenanceReader as h, ExperimentRep as i, ExperimentVerdict as l, fileExperimentStore as m, Experiment as n, ExperimentStore as o, computeExperimentStats as p, ExperimentProvenance as r, ExperimentTracker as s, CreateExperimentInput as t, ImprovementThresholds as u, ClusterBootstrapInterval as v, ClusteredPairedBinaryResult as w, ClusteredBinaryCluster as x, ClusterSignFlipAlternative as y };
-//# sourceMappingURL=experiment-tracker-IMntXr6J.d.ts.map
+export { requiredSampleSize as _, ExperimentVerdict as a, computeExperimentStats as c, inMemoryExperimentStore as d, mulberry32 as f, requiredPairedSampleSize as g, pairedMde as h, ExperimentTracker as i, fileExperimentStore as l, mcnemarRequiredN as m, ExperimentRep as n, ImprovementThresholds as o, mcnemarPower as p, ExperimentStats as r, ImprovementVerdictResult as s, Experiment as t, improvementVerdict as u };
+//# sourceMappingURL=experiment-tracker-DWHZBAYL.d.ts.map

package/dist/experiment-tracker-DWHZBAYL.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment-tracker-DWHZBAYL.d.ts","names":[],"sources":["../src/statistics/power-and-mde.ts","../src/statistics/random.ts","../src/experiment-tracker.ts"],"mappings":";;;;;;;iBAWgB,mBAAmB;EACjC;EACA;EACA;EACA;;;;;;;;;;;iBAsBc,yBAAyB;EACvC;EACA;EACA;EACA;;;;;;;;iBAkBc,UAAU;EACxB;EACA;EACA;EACA;;;;;;;;;;;;;;;;iBAyBc,iBAAiB;EAC/B;EACA;EACA;EACA;EACA;;;;;;;iBAyBc,aAAa;EAC3B;EACA;EACA;EACA;EACA;;;;;;;;iBCrHc,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCwBf;;UAGK;;EAEf;;EAEA;;EAEA;;;;UAKe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA,UAAU;;UAGK;EACf;EACA;EACA;EACA;;EAEA;;EAEA;;;EAGA;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;EAEA,YAAY;;EAEZ;;EAEA;EACA,MAAM;EACN,OAAO;EACP,SAAS;;EAET;;UAGe;;EAEf;;EAEA;;EAEA;;EAEA;;;EAGA;;UAGe;EACf,SAAS;;EAET;;EAEA;;;;;;;iBAkDc,uBACd,MAAM,iBACN,aAAa,wBACZ;;;;;;;iBAgDa,mBACd,WAAW,iBACX,QAAQ,wBACR,aAAa,wBACZ;;;KA6CS,yBAAyB,uBAAuB,QAAQ;;;UAInD;EACf,QAAQ,QAAQ;EAChB,KAAK,aAAa,eAAe;;;;iBAoBnB,wBAAwB,UAAS,eAAoB;;iBAarD,oBAAoB,eAAe;UAyBlC;EACf,QAAQ;EACR,mBAAmB;EACnB,aAAa;;EAEb;;UAGe;EACf;EACA;EACA;EACA;;EAEA,aAAa;;;;;;;;;cAUF;mBACM;mBACA;mBACA;mBACA;EAEjB,YAAY,UAAS;EAOf,OAAO,OAAO,wBAAwB,QAAQ;;;EA6B9C,OACJ,sBACA,KAAK,KAAK;IAAwC;IAAc;MAC/D,QAAQ;EAoBL,IAAI,uBAAuB,QAAQ;EAMnC,QAAQ,QAAQ;;EAKhB,WAAW,uBAAuB,QAAQ"}

package/dist/{external-optimizer-contracts-CZuJNcT5.d.ts → external-optimizer-contracts-lixrOZdX.d.ts}

@@ -1,5 +1,5 @@
-import { b as CustomTokenPricing, g as CostReceiptInput } from "./cost-ledger-Bv_e8XHY.js";
-import { M as ChatResponse, j as ChatRequest } from "./types-D216SgwM.js";
+import { b as CustomTokenPricing, g as CostReceiptInput } from "./cost-ledger-DbQdN3nO.js";
+import { h as ChatResponse, m as ChatRequest } from "./types-Cx3YUh2r.js";
 //#region src/campaign/external-optimizer-contracts.d.ts
 interface ExternalOptimizerProcessLimits {
   /** Maximum serialized input written for the child process. */
@@ -162,4 +162,4 @@ interface ExternalOptimizerModelBudget {
 }
 //#endregion
 export { ExternalTextEvaluationRequest as _, ExternalOptimizerEndpointFormat as a, ExternalOptimizerModelBudget as c, ExternalOptimizerModelCallResult as d, ExternalOptimizerModelExecutionObservation as f, ExternalTextCandidate as g, ExternalOptimizerRunnerCommand as h, ExternalOptimizerChatRequest as i, ExternalOptimizerModelCall as l, ExternalOptimizerResumeMode as m, DEFAULT_EXTERNAL_OPTIMIZER_PROCESS_LIMITS as n, ExternalOptimizerEvaluationObservation as o, ExternalOptimizerProcessLimits as p, ExternalOptimizerCallbackLimits as r, ExternalOptimizerEvaluationRefusalReason as s, DEFAULT_EXTERNAL_OPTIMIZER_CALLBACK_LIMITS as t, ExternalOptimizerModelCallRequest as u, resolveExternalOptimizerCallbackLimits as v, resolveExternalOptimizerProcessLimits as y };
-//# sourceMappingURL=external-optimizer-contracts-CZuJNcT5.d.ts.map
+//# sourceMappingURL=external-optimizer-contracts-lixrOZdX.d.ts.map

package/dist/{external-optimizer-contracts-CZuJNcT5.d.ts.map → external-optimizer-contracts-lixrOZdX.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"external-optimizer-contracts-CZuJNcT5.d.ts","names":[],"sources":["../src/campaign/external-optimizer-contracts.ts"],"mappings":";;;UAWiB;;EAEf;;EAEA;;EAEA;;cAGW,2CAA2C,SAAS;UAOhD;;EAEf;;EAEA;;cAGW,4CAA4C,SAAS;UAMjD;EACf;EACA;EACA,MAAM,OAAO;;EAEb,SAAS,QAAQ;;KAGP;KAEA,iCAAiC;UAE5B;EACf,WAAW;EACX;;iBAUc,sCACd,OAAO,QAAQ,6CACf,iBACC;iBAmBa,uCACd,OAAO,QAAQ,8CACf,iBACC;KAkBE,aAAa,KAAK,eAAc,6BACjC,IACA,0BAA0B,gBACf,aAAa,OACtB,+BACc,WAAW,IAAI,aAAa,EAAE,SAC1C;;KAGI,+BAA+B,aACzC,KAAK;EAA0B;;KAGrB;;UAGK;;WAEN;;WAEA,SAAS;;WAET,iBAAiB;WACjB,QAAQ;;;KAIP;WAEG;;WAEA,UAAU;;;;;;;WAOV,SAPU;;WASV;;WAGA;;WAEA;;WAEA,SATkC;;WAWlC;;;;;;;;;;;;KAaH,8BACV,SAAS,sCACN,QAAQ;;KAGD;WAEG;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;KAGH;;;;;;KAUA;WAEG;WACA;WACA,WAAW;WACX;;WAGA;WACA;WACA,WAAW;WACX;WACA;;WAEA;WACA;;WAGA;WACA;WACA,QAAQ;WACR,YAAY;WACZ;WACA;;UAGE;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;EAUA;;;;;;EAMA,UAAU;;EAEV"}
+{"version":3,"file":"external-optimizer-contracts-lixrOZdX.d.ts","names":[],"sources":["../src/campaign/external-optimizer-contracts.ts"],"mappings":";;;UAWiB;;EAEf;;EAEA;;EAEA;;cAGW,2CAA2C,SAAS;UAOhD;;EAEf;;EAEA;;cAGW,4CAA4C,SAAS;UAMjD;EACf;EACA;EACA,MAAM,OAAO;;EAEb,SAAS,QAAQ;;KAGP;KAEA,iCAAiC;UAE5B;EACf,WAAW;EACX;;iBAUc,sCACd,OAAO,QAAQ,6CACf,iBACC;iBAmBa,uCACd,OAAO,QAAQ,8CACf,iBACC;KAkBE,aAAa,KAAK,eAAc,6BACjC,IACA,0BAA0B,gBACf,aAAa,OACtB,+BACc,WAAW,IAAI,aAAa,EAAE,SAC1C;;KAGI,+BAA+B,aACzC,KAAK;EAA0B;;KAGrB;;UAGK;;WAEN;;WAEA,SAAS;;WAET,iBAAiB;WACjB,QAAQ;;;KAIP;WAEG;;WAEA,UAAU;;;;;;;WAOV,SAPU;;WASV;;WAGA;;WAEA;;WAEA,SATkC;;WAWlC;;;;;;;;;;;;KAaH,8BACV,SAAS,sCACN,QAAQ;;KAGD;WAEG;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;KAGH;;;;;;KAUA;WAEG;WACA;WACA,WAAW;WACX;;WAGA;WACA;WACA,WAAW;WACX;WACA;;WAEA;WACA;;WAGA;WACA;WACA,QAAQ;WACR,YAAY;WACZ;WACA;;UAGE;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;EAUA;;;;;;EAMA,UAAU;;EAEV"}