@tangle-network/agent-eval 0.216.0 → 0.217.1

package/dist/interval-Dq9gt7jx.js

@@ -0,0 +1,219 @@
+import { s as ValidationError } from "./errors-BcOs5MKW.js";
+import { t as mulberry32 } from "./random-DDDcC7YU.js";
+import { n as evaluatePredicate, r as readField } from "./predicate-FdKmElA_.js";
+//#region src/experiment/ast/estimand.ts
+function evaluateSetExpr(expr, rows, armField, idField) {
+	if (expr.kind === "rows-where") {
+		const ids = /* @__PURE__ */ new Set();
+		for (const row of rows) {
+			if (String(readField(row, armField)) !== expr.arm) continue;
+			if (evaluatePredicate(expr.event, row)) ids.add(String(readField(row, idField)));
+		}
+		return ids;
+	}
+	if (expr.of.length === 0) throw new ValidationError("computeEstimand: empty intersect");
+	const [first, ...rest] = expr.of.map((e) => evaluateSetExpr(e, rows, armField, idField));
+	const out = /* @__PURE__ */ new Set();
+	for (const id of first) if (rest.every((s) => s.has(id))) out.add(id);
+	return out;
+}
+/**
+* Read one registered outcome field as a number.
+*
+* A binary outcome reaches evidence as `true` or `false`. Its mean is the pass
+* rate and the mean of its paired differences is the risk difference, so
+* `true` reads as 1 and `false` as 0 — the same quantity a caller would
+* otherwise encode by hand, and the same reading in every interpreter here.
+* Every other type, and a non-finite number, is a measurement defect: it
+* rejects instead of poisoning the mean with `NaN` or a coerced zero.
+*/
+function readNumericOutcome(raw, context, field, where) {
+	if (typeof raw === "boolean") return raw ? 1 : 0;
+	if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+	throw new ValidationError(`${context}: value field '${field}' is not a finite number or a boolean on ${where}`);
+}
+/** Compute an estimand over evidence rows. Pure; reads only registered fields. */
+function computeEstimand(estimand, rows) {
+	switch (estimand.kind) {
+		case "rate": {
+			const numerator = rows.filter((r) => evaluatePredicate(estimand.event, r)).length;
+			if (rows.length === 0) throw new ValidationError("computeEstimand: rate over zero rows");
+			return {
+				value: numerator / rows.length,
+				numerator,
+				denominator: rows.length
+			};
+		}
+		case "rate-at-least-once": {
+			const byGroup = /* @__PURE__ */ new Map();
+			for (const row of rows) {
+				const group = String(readField(row, estimand.groupBy));
+				const hit = evaluatePredicate(estimand.event, row);
+				byGroup.set(group, (byGroup.get(group) ?? false) || hit);
+			}
+			if (byGroup.size === 0) throw new ValidationError("computeEstimand: rate-at-least-once over zero groups");
+			const numerator = [...byGroup.values()].filter(Boolean).length;
+			return {
+				value: numerator / byGroup.size,
+				numerator,
+				denominator: byGroup.size
+			};
+		}
+		case "paired-mean-diff": {
+			const byPair = /* @__PURE__ */ new Map();
+			for (const row of rows) {
+				const arm = String(readField(row, estimand.armField));
+				if (arm !== estimand.treatment && arm !== estimand.control) continue;
+				const pair = String(readField(row, estimand.pairBy));
+				const value = readNumericOutcome(readField(row, estimand.value), "computeEstimand paired-mean-diff", estimand.value, `pair '${pair}'`);
+				const slot = byPair.get(pair) ?? {};
+				if (arm === estimand.treatment) slot.treatment = value;
+				else slot.control = value;
+				byPair.set(pair, slot);
+			}
+			if (byPair.size === 0) throw new ValidationError("computeEstimand: paired-mean-diff over zero pairs");
+			let sum = 0;
+			for (const slot of byPair.values()) sum += (slot.treatment ?? 0) - (slot.control ?? 0);
+			return {
+				value: sum / byPair.size,
+				numerator: sum,
+				denominator: byPair.size
+			};
+		}
+		case "set-ratio": {
+			const numeratorSet = evaluateSetExpr(estimand.numerator, rows, estimand.armField, estimand.idField);
+			const denominatorSet = evaluateSetExpr(estimand.denominator, rows, estimand.armField, estimand.idField);
+			if (denominatorSet.size === 0) throw new ValidationError("computeEstimand: set-ratio denominator set is empty");
+			return {
+				value: numeratorSet.size / denominatorSet.size,
+				numerator: numeratorSet.size,
+				denominator: denominatorSet.size
+			};
+		}
+	}
+}
+//#endregion
+//#region src/experiment/ast/interval.ts
+/** Shared by registration and direct execution so malformed intervals cannot produce evidence. */
+function intervalSpecProblems(spec) {
+	if (spec === null || typeof spec !== "object" || Array.isArray(spec)) return ["interval must be an object"];
+	if (spec.kind !== "cluster-bootstrap" && spec.kind !== "clopper-pearson") return ["interval kind must be cluster-bootstrap or clopper-pearson"];
+	const problems = [];
+	if (!Number.isFinite(spec.level) || spec.level <= 0 || spec.level >= 1) problems.push("level must be a finite number between zero and one");
+	if (spec.kind === "cluster-bootstrap") {
+		for (const field of ["clusterBy", "value"]) {
+			const path = spec[field];
+			if (typeof path !== "string" || path.split(".").some((segment) => segment.length === 0 || segment.trim() !== segment)) problems.push(`${field} must be a nonempty dot-separated field path`);
+		}
+		if (!Number.isSafeInteger(spec.resamples) || spec.resamples < 1 || spec.resamples > 4294967295) problems.push("resamples must be a positive integer within the supported array length");
+		if (!Number.isSafeInteger(spec.seed)) problems.push("seed must be a safe integer");
+		if (spec.method !== "percentile") problems.push("method must be percentile");
+	}
+	return problems;
+}
+/**
+* Execute an interval spec.
+*
+* Cluster-bootstrap resamples whole clusters of its registered `value` field and
+* takes percentile bounds of the pooled mean. Clopper-Pearson computes the
+* exact binomial interval and requires `successes`/`trials` evidence instead
+* of rows.
+*/
+function computeInterval(spec, evidence) {
+	const problems = intervalSpecProblems(spec);
+	if (problems.length > 0) throw new ValidationError(`computeInterval: ${problems.join("; ")}`);
+	if (evidence === null || typeof evidence !== "object" || Array.isArray(evidence)) throw new ValidationError("computeInterval: evidence must be an object");
+	if (spec.kind === "cluster-bootstrap") {
+		if (evidence.kind !== "rows") throw new ValidationError("computeInterval: cluster-bootstrap requires row evidence");
+		if ("value" in evidence) throw new ValidationError("computeInterval: register value in the interval spec, not row evidence");
+		if (!Array.isArray(evidence.rows)) throw new ValidationError("computeInterval: rows must be an array");
+		const clusters = /* @__PURE__ */ new Map();
+		for (const [index, row] of evidence.rows.entries()) {
+			if (row === null || typeof row !== "object" || Array.isArray(row)) throw new ValidationError(`computeInterval: row ${index} must be an object`);
+			const cluster = readField(row, spec.clusterBy);
+			if (!(typeof cluster === "string" && cluster.length > 0 && cluster.trim() === cluster) && !(typeof cluster === "number" && Number.isFinite(cluster))) throw new ValidationError(`computeInterval: cluster field '${spec.clusterBy}' must be a nonempty string or finite number on row ${index}`);
+			const clusterKey = `${typeof cluster}:${cluster}`;
+			const value = readNumericOutcome(readField(row, spec.value), "computeInterval cluster-bootstrap", spec.value, `cluster '${cluster}'`);
+			const bucket = clusters.get(clusterKey);
+			if (bucket) bucket.push(value);
+			else clusters.set(clusterKey, [value]);
+		}
+		const clusterValues = [...clusters.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, values]) => values);
+		if (clusterValues.length < 2) throw new ValidationError(`computeInterval: cluster-bootstrap needs >= 2 clusters, got ${clusterValues.length}`);
+		const rng = mulberry32(spec.seed);
+		const means = new Array(spec.resamples);
+		for (let draw = 0; draw < spec.resamples; draw++) {
+			let sum = 0;
+			let count = 0;
+			for (let pick = 0; pick < clusterValues.length; pick++) {
+				const cluster = clusterValues[Math.floor(rng() * clusterValues.length)];
+				for (const value of cluster) sum += value;
+				count += cluster.length;
+			}
+			means[draw] = sum / count;
+			if (!Number.isFinite(means[draw])) throw new ValidationError("computeInterval: cluster mean overflowed the finite numeric range");
+		}
+		means.sort((a, b) => a - b);
+		const alpha = 1 - spec.level;
+		const lowerIndex = Math.floor(alpha / 2 * spec.resamples);
+		const upperIndex = Math.min(spec.resamples - 1, Math.ceil((1 - alpha / 2) * spec.resamples) - 1);
+		return {
+			lower: means[lowerIndex],
+			upper: means[Math.max(lowerIndex, upperIndex)],
+			level: spec.level
+		};
+	}
+	if (evidence.kind !== "binomial") throw new ValidationError("computeInterval: clopper-pearson requires binomial evidence");
+	const { successes, trials } = evidence;
+	if (!Number.isSafeInteger(successes) || !Number.isSafeInteger(trials) || trials <= 0 || successes < 0) throw new ValidationError(`computeInterval: clopper-pearson needs 0 <= successes <= trials, got ${successes}/${trials}`);
+	if (successes > trials) throw new ValidationError(`computeInterval: clopper-pearson successes ${successes} exceed trials ${trials}`);
+	const alpha = 1 - spec.level;
+	return {
+		lower: successes === 0 ? 0 : binomialQuantile(successes, trials, alpha / 2, "lower"),
+		upper: successes === trials ? 1 : binomialQuantile(successes, trials, alpha / 2, "upper"),
+		level: spec.level
+	};
+}
+/**
+* Clopper-Pearson bound by bisection on the binomial tail. The lower bound is
+* the p with P(X >= successes | p) = alpha; the upper is the p with
+* P(X <= successes | p) = alpha. Deterministic, no special functions.
+*/
+function binomialQuantile(successes, trials, alpha, side) {
+	const tail = (p) => {
+		let sum = 0;
+		for (let k = 0; k <= trials; k++) {
+			if (!(side === "lower" ? k >= successes : k <= successes)) continue;
+			sum += Math.exp(logBinomialPmf(k, trials, p));
+		}
+		return sum;
+	};
+	let lo = 0;
+	let hi = 1;
+	for (let iter = 0; iter < 100; iter++) {
+		const mid = (lo + hi) / 2;
+		if (tail(mid) < alpha) {
+			if (side === "lower") lo = mid;
+			else hi = mid;
+		} else if (side === "lower") hi = mid;
+		else lo = mid;
+	}
+	return (lo + hi) / 2;
+}
+function logBinomialPmf(k, n, p) {
+	if (p <= 0) return k === 0 ? 0 : Number.NEGATIVE_INFINITY;
+	if (p >= 1) return k === n ? 0 : Number.NEGATIVE_INFINITY;
+	return logChoose(n, k) + k * Math.log(p) + (n - k) * Math.log(1 - p);
+}
+function logChoose(n, k) {
+	return logFactorial(n) - logFactorial(k) - logFactorial(n - k);
+}
+const LOG_FACTORIAL_CACHE = [0];
+function logFactorial(n) {
+	for (let i = LOG_FACTORIAL_CACHE.length; i <= n; i++) LOG_FACTORIAL_CACHE[i] = LOG_FACTORIAL_CACHE[i - 1] + Math.log(i);
+	return LOG_FACTORIAL_CACHE[n];
+}
+//#endregion
+export { intervalSpecProblems as n, computeEstimand as r, computeInterval as t };
+
+//# sourceMappingURL=interval-Dq9gt7jx.js.map

package/dist/interval-Dq9gt7jx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interval-Dq9gt7jx.js","names":[],"sources":["../src/experiment/ast/estimand.ts","../src/experiment/ast/interval.ts"],"sourcesContent":["import { ValidationError } from '../../errors'\nimport type { EvidenceRecord } from './evidence'\nimport { evaluatePredicate, type Predicate, readField } from './predicate'\n\n// ── Estimands ────────────────────────────────────────────────────────\n\n/** A named set of row identities, built from arm rows and an event predicate. */\nexport type SetExpr =\n  | { kind: 'rows-where'; arm: string; event: Predicate }\n  | { kind: 'intersect'; of: SetExpr[] }\n\n/**\n * What the experiment measures. Every estimand names the fields it reads, so\n * the sealed tree records the full data dependency of the number.\n */\nexport type Estimand =\n  | { kind: 'rate'; event: Predicate; over: 'rollouts' }\n  | { kind: 'rate-at-least-once'; event: Predicate; groupBy: string }\n  | {\n      kind: 'paired-mean-diff'\n      armField: string\n      treatment: string\n      control: string\n      pairBy: string\n      /**\n       * Field path to the per-row outcome. A boolean reads as 1 or 0, so a\n       * binary pass/fail outcome gives the risk difference directly.\n       */\n      value: string\n      /** A pair one arm did not answer contributes a difference of exactly zero. */\n      missing: 'zero-diff'\n    }\n  | {\n      kind: 'set-ratio'\n      armField: string\n      idField: string\n      numerator: SetExpr\n      denominator: SetExpr\n    }\n\nexport interface EstimandResult {\n  value: number\n  numerator: number\n  denominator: number\n}\n\nfunction evaluateSetExpr(\n  expr: SetExpr,\n  rows: readonly EvidenceRecord[],\n  armField: string,\n  idField: string,\n): Set<string> {\n  if (expr.kind === 'rows-where') {\n    const ids = new Set<string>()\n    for (const row of rows) {\n      if (String(readField(row, armField)) !== expr.arm) continue\n      if (evaluatePredicate(expr.event, row)) ids.add(String(readField(row, idField)))\n    }\n    return ids\n  }\n  if (expr.of.length === 0) throw new ValidationError('computeEstimand: empty intersect')\n  const sets = expr.of.map((e) => evaluateSetExpr(e, rows, armField, idField))\n  const [first, ...rest] = sets\n  const out = new Set<string>()\n  for (const id of first!) {\n    if (rest.every((s) => s.has(id))) out.add(id)\n  }\n  return out\n}\n\n/**\n * Read one registered outcome field as a number.\n *\n * A binary outcome reaches evidence as `true` or `false`. Its mean is the pass\n * rate and the mean of its paired differences is the risk difference, so\n * `true` reads as 1 and `false` as 0 — the same quantity a caller would\n * otherwise encode by hand, and the same reading in every interpreter here.\n * Every other type, and a non-finite number, is a measurement defect: it\n * rejects instead of poisoning the mean with `NaN` or a coerced zero.\n */\nexport function readNumericOutcome(\n  raw: unknown,\n  context: string,\n  field: string,\n  where: string,\n): number {\n  if (typeof raw === 'boolean') return raw ? 1 : 0\n  if (typeof raw === 'number' && Number.isFinite(raw)) return raw\n  throw new ValidationError(\n    `${context}: value field '${field}' is not a finite number or a boolean on ${where}`,\n  )\n}\n\n/** Compute an estimand over evidence rows. Pure; reads only registered fields. */\nexport function computeEstimand(\n  estimand: Estimand,\n  rows: readonly EvidenceRecord[],\n): EstimandResult {\n  switch (estimand.kind) {\n    case 'rate': {\n      const numerator = rows.filter((r) => evaluatePredicate(estimand.event, r)).length\n      if (rows.length === 0) throw new ValidationError('computeEstimand: rate over zero rows')\n      return { value: numerator / rows.length, numerator, denominator: rows.length }\n    }\n    case 'rate-at-least-once': {\n      const byGroup = new Map<string, boolean>()\n      for (const row of rows) {\n        const group = String(readField(row, estimand.groupBy))\n        const hit = evaluatePredicate(estimand.event, row)\n        byGroup.set(group, (byGroup.get(group) ?? false) || hit)\n      }\n      if (byGroup.size === 0) {\n        throw new ValidationError('computeEstimand: rate-at-least-once over zero groups')\n      }\n      const numerator = [...byGroup.values()].filter(Boolean).length\n      return { value: numerator / byGroup.size, numerator, denominator: byGroup.size }\n    }\n    case 'paired-mean-diff': {\n      const byPair = new Map<string, { treatment?: number; control?: number }>()\n      for (const row of rows) {\n        const arm = String(readField(row, estimand.armField))\n        if (arm !== estimand.treatment && arm !== estimand.control) continue\n        const pair = String(readField(row, estimand.pairBy))\n        const value = readNumericOutcome(\n          readField(row, estimand.value),\n          'computeEstimand paired-mean-diff',\n          estimand.value,\n          `pair '${pair}'`,\n        )\n        const slot = byPair.get(pair) ?? {}\n        if (arm === estimand.treatment) slot.treatment = value\n        else slot.control = value\n        byPair.set(pair, slot)\n      }\n      if (byPair.size === 0) {\n        throw new ValidationError('computeEstimand: paired-mean-diff over zero pairs')\n      }\n      let sum = 0\n      for (const slot of byPair.values()) {\n        // missing: 'zero-diff' — an unanswered side contributes zero, never a drop\n        sum += (slot.treatment ?? 0) - (slot.control ?? 0)\n      }\n      return { value: sum / byPair.size, numerator: sum, denominator: byPair.size }\n    }\n    case 'set-ratio': {\n      const numeratorSet = evaluateSetExpr(\n        estimand.numerator,\n        rows,\n        estimand.armField,\n        estimand.idField,\n      )\n      const denominatorSet = evaluateSetExpr(\n        estimand.denominator,\n        rows,\n        estimand.armField,\n        estimand.idField,\n      )\n      if (denominatorSet.size === 0) {\n        throw new ValidationError('computeEstimand: set-ratio denominator set is empty')\n      }\n      return {\n        value: numeratorSet.size / denominatorSet.size,\n        numerator: numeratorSet.size,\n        denominator: denominatorSet.size,\n      }\n    }\n  }\n}\n","import { ValidationError } from '../../errors'\nimport { mulberry32 } from '../../statistics'\nimport { readNumericOutcome } from './estimand'\nimport type { EvidenceRecord } from './evidence'\nimport { readField } from './predicate'\n\n// ── Intervals ────────────────────────────────────────────────────────\n\n/** How uncertainty is computed. The seed is part of the registration. */\nexport type IntervalSpec =\n  | {\n      kind: 'cluster-bootstrap'\n      clusterBy: string\n      /** Registered numeric or boolean outcome field, including a prepared paired difference. */\n      value: string\n      resamples: number\n      seed: number\n      level: number\n      method: 'percentile'\n    }\n  | { kind: 'clopper-pearson'; level: number }\n\nexport interface ComputedInterval {\n  lower: number\n  upper: number\n  level: number\n}\n\n/** Shared by registration and direct execution so malformed intervals cannot produce evidence. */\nexport function intervalSpecProblems(spec: IntervalSpec): string[] {\n  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {\n    return ['interval must be an object']\n  }\n  if (spec.kind !== 'cluster-bootstrap' && spec.kind !== 'clopper-pearson') {\n    return ['interval kind must be cluster-bootstrap or clopper-pearson']\n  }\n  const problems: string[] = []\n  if (!Number.isFinite(spec.level) || spec.level <= 0 || spec.level >= 1) {\n    problems.push('level must be a finite number between zero and one')\n  }\n  if (spec.kind === 'cluster-bootstrap') {\n    for (const field of ['clusterBy', 'value'] as const) {\n      const path = spec[field]\n      if (\n        typeof path !== 'string' ||\n        path.split('.').some((segment) => segment.length === 0 || segment.trim() !== segment)\n      ) {\n        problems.push(`${field} must be a nonempty dot-separated field path`)\n      }\n    }\n    if (\n      !Number.isSafeInteger(spec.resamples) ||\n      spec.resamples < 1 ||\n      spec.resamples > 0xffff_ffff\n    ) {\n      problems.push('resamples must be a positive integer within the supported array length')\n    }\n    if (!Number.isSafeInteger(spec.seed)) problems.push('seed must be a safe integer')\n    if (spec.method !== 'percentile') problems.push('method must be percentile')\n  }\n  return problems\n}\n\n/**\n * Execute an interval spec.\n *\n * Cluster-bootstrap resamples whole clusters of its registered `value` field and\n * takes percentile bounds of the pooled mean. Clopper-Pearson computes the\n * exact binomial interval and requires `successes`/`trials` evidence instead\n * of rows.\n */\nexport function computeInterval(\n  spec: IntervalSpec,\n  evidence:\n    | { kind: 'rows'; rows: readonly EvidenceRecord[] }\n    | { kind: 'binomial'; successes: number; trials: number },\n): ComputedInterval {\n  const problems = intervalSpecProblems(spec)\n  if (problems.length > 0) throw new ValidationError(`computeInterval: ${problems.join('; ')}`)\n  if (evidence === null || typeof evidence !== 'object' || Array.isArray(evidence)) {\n    throw new ValidationError('computeInterval: evidence must be an object')\n  }\n  if (spec.kind === 'cluster-bootstrap') {\n    if (evidence.kind !== 'rows') {\n      throw new ValidationError('computeInterval: cluster-bootstrap requires row evidence')\n    }\n    if ('value' in evidence) {\n      throw new ValidationError(\n        'computeInterval: register value in the interval spec, not row evidence',\n      )\n    }\n    if (!Array.isArray(evidence.rows))\n      throw new ValidationError('computeInterval: rows must be an array')\n    const clusters = new Map<string, number[]>()\n    for (const [index, row] of evidence.rows.entries()) {\n      if (row === null || typeof row !== 'object' || Array.isArray(row)) {\n        throw new ValidationError(`computeInterval: row ${index} must be an object`)\n      }\n      const cluster = readField(row, spec.clusterBy)\n      if (\n        !(typeof cluster === 'string' && cluster.length > 0 && cluster.trim() === cluster) &&\n        !(typeof cluster === 'number' && Number.isFinite(cluster))\n      ) {\n        throw new ValidationError(\n          `computeInterval: cluster field '${spec.clusterBy}' must be a nonempty string or finite number on row ${index}`,\n        )\n      }\n      const clusterKey = `${typeof cluster}:${cluster}`\n      const value = readNumericOutcome(\n        readField(row, spec.value),\n        'computeInterval cluster-bootstrap',\n        spec.value,\n        `cluster '${cluster}'`,\n      )\n      const bucket = clusters.get(clusterKey)\n      if (bucket) bucket.push(value)\n      else clusters.set(clusterKey, [value])\n    }\n    const clusterValues = [...clusters.entries()]\n      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n      .map(([, values]) => values)\n    if (clusterValues.length < 2) {\n      throw new ValidationError(\n        `computeInterval: cluster-bootstrap needs >= 2 clusters, got ${clusterValues.length}`,\n      )\n    }\n    const rng = mulberry32(spec.seed)\n    const means = new Array<number>(spec.resamples)\n    for (let draw = 0; draw < spec.resamples; draw++) {\n      let sum = 0\n      let count = 0\n      for (let pick = 0; pick < clusterValues.length; pick++) {\n        const cluster = clusterValues[Math.floor(rng() * clusterValues.length)]!\n        for (const value of cluster) sum += value\n        count += cluster.length\n      }\n      means[draw] = sum / count\n      if (!Number.isFinite(means[draw])) {\n        throw new ValidationError(\n          'computeInterval: cluster mean overflowed the finite numeric range',\n        )\n      }\n    }\n    means.sort((a, b) => a - b)\n    const alpha = 1 - spec.level\n    const lowerIndex = Math.floor((alpha / 2) * spec.resamples)\n    const upperIndex = Math.min(spec.resamples - 1, Math.ceil((1 - alpha / 2) * spec.resamples) - 1)\n    return {\n      lower: means[lowerIndex]!,\n      upper: means[Math.max(lowerIndex, upperIndex)]!,\n      level: spec.level,\n    }\n  }\n\n  if (evidence.kind !== 'binomial') {\n    throw new ValidationError('computeInterval: clopper-pearson requires binomial evidence')\n  }\n  const { successes, trials } = evidence\n  if (\n    !Number.isSafeInteger(successes) ||\n    !Number.isSafeInteger(trials) ||\n    trials <= 0 ||\n    successes < 0\n  ) {\n    throw new ValidationError(\n      `computeInterval: clopper-pearson needs 0 <= successes <= trials, got ${successes}/${trials}`,\n    )\n  }\n  if (successes > trials) {\n    throw new ValidationError(\n      `computeInterval: clopper-pearson successes ${successes} exceed trials ${trials}`,\n    )\n  }\n  const alpha = 1 - spec.level\n  const lower = successes === 0 ? 0 : binomialQuantile(successes, trials, alpha / 2, 'lower')\n  const upper = successes === trials ? 1 : binomialQuantile(successes, trials, alpha / 2, 'upper')\n  return { lower, upper, level: spec.level }\n}\n\n/**\n * Clopper-Pearson bound by bisection on the binomial tail. The lower bound is\n * the p with P(X >= successes | p) = alpha; the upper is the p with\n * P(X <= successes | p) = alpha. Deterministic, no special functions.\n */\nfunction binomialQuantile(\n  successes: number,\n  trials: number,\n  alpha: number,\n  side: 'lower' | 'upper',\n): number {\n  const tail = (p: number): number => {\n    // log-space binomial pmf accumulation for numeric stability\n    let sum = 0\n    for (let k = 0; k <= trials; k++) {\n      const inTail = side === 'lower' ? k >= successes : k <= successes\n      if (!inTail) continue\n      sum += Math.exp(logBinomialPmf(k, trials, p))\n    }\n    return sum\n  }\n  let lo = 0\n  let hi = 1\n  for (let iter = 0; iter < 100; iter++) {\n    const mid = (lo + hi) / 2\n    if (tail(mid) < alpha) {\n      if (side === 'lower') lo = mid\n      else hi = mid\n    } else {\n      if (side === 'lower') hi = mid\n      else lo = mid\n    }\n  }\n  return (lo + hi) / 2\n}\n\nfunction logBinomialPmf(k: number, n: number, p: number): number {\n  if (p <= 0) return k === 0 ? 0 : Number.NEGATIVE_INFINITY\n  if (p >= 1) return k === n ? 0 : Number.NEGATIVE_INFINITY\n  return logChoose(n, k) + k * Math.log(p) + (n - k) * Math.log(1 - p)\n}\n\nfunction logChoose(n: number, k: number): number {\n  return logFactorial(n) - logFactorial(k) - logFactorial(n - k)\n}\n\nconst LOG_FACTORIAL_CACHE: number[] = [0]\n\nfunction logFactorial(n: number): number {\n  for (let i = LOG_FACTORIAL_CACHE.length; i <= n; i++) {\n    LOG_FACTORIAL_CACHE[i] = LOG_FACTORIAL_CACHE[i - 1]! + Math.log(i)\n  }\n  return LOG_FACTORIAL_CACHE[n]!\n}\n"],"mappings":"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"}

package/dist/interval-ohuOJurX.d.ts

@@ -0,0 +1,47 @@
+//#region src/experiment/ast/evidence.d.ts
+/** JSON-serializable value — everything a sealed node may carry. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [k: string]: JsonValue;
+};
+/** Evidence row shape. Fields are addressed by dot-separated paths. */
+type EvidenceRecord = Record<string, unknown>;
+//#endregion
+//#region src/experiment/ast/interval.d.ts
+/** How uncertainty is computed. The seed is part of the registration. */
+type IntervalSpec = {
+  kind: 'cluster-bootstrap';
+  clusterBy: string;
+  /** Registered numeric or boolean outcome field, including a prepared paired difference. */
+  value: string;
+  resamples: number;
+  seed: number;
+  level: number;
+  method: 'percentile';
+} | {
+  kind: 'clopper-pearson';
+  level: number;
+};
+interface ComputedInterval {
+  lower: number;
+  upper: number;
+  level: number;
+}
+/**
+ * Execute an interval spec.
+ *
+ * Cluster-bootstrap resamples whole clusters of its registered `value` field and
+ * takes percentile bounds of the pooled mean. Clopper-Pearson computes the
+ * exact binomial interval and requires `successes`/`trials` evidence instead
+ * of rows.
+ */
+declare function computeInterval(spec: IntervalSpec, evidence: {
+  kind: 'rows';
+  rows: readonly EvidenceRecord[];
+} | {
+  kind: 'binomial';
+  successes: number;
+  trials: number;
+}): ComputedInterval;
+//#endregion
+export { JsonValue as a, EvidenceRecord as i, IntervalSpec as n, computeInterval as r, ComputedInterval as t };
+//# sourceMappingURL=interval-ohuOJurX.d.ts.map

package/dist/interval-ohuOJurX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interval-ohuOJurX.d.ts","names":[],"sources":["../src/experiment/ast/evidence.ts","../src/experiment/ast/interval.ts"],"mappings":";;KACY,+CAA+C;GAAiB,YAAY;;;KAG5E,iBAAiB;;;;KCKjB;EAEN;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;EAAyB;;UAEd;EACf;EACA;EACA;;;;;;;;;;iBA8Cc,gBACd,MAAM,cACN;EACM;EAAc,eAAe;;EAC7B;EAAkB;EAAmB;IAC1C"}

package/dist/{journal-DvKCvjty.js → journal-CR4QikYp.js}

@@ -1,4 +1,4 @@
-import { a as hashCanonical, r as canonicalString, t as LEDGER_HASH_PATTERN } from "./canonical-BsZVgBhW.js";
+import { a as hashCanonical, r as canonicalString, t as LEDGER_HASH_PATTERN } from "./canonical-Dq2hOQ8L.js";
 import { t as deepFreezeCanonicalJson } from "./deep-freeze-CurcOQg3.js";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
@@ -239,113 +239,6 @@ function unlinkIfExists(path) {
 	}
 }
 //#endregion
-//#region src/concurrency.ts
-/**
-* concurrency — small primitives the evolution loop needs.
-*
-* `Mutex` is a zero-dep async lock with FIFO fairness. The evolution loop
-* uses it to serialise checkout/build/commit sequences inside a single
-* pool slot, and to gate concurrent JSONL writers (see
-* `lockedJsonlReferenceReplayStore`).
-*
-* Deliberately minimal — no priority queue, no timeouts. If you need
-* those, swap to `async-mutex` at the call site.
-*/
-var Mutex = class {
-	locked = false;
-	waiters = [];
-	async acquire() {
-		if (!this.locked) {
-			this.locked = true;
-			return () => this.release();
-		}
-		return new Promise((resolve) => {
-			this.waiters.push(() => {
-				resolve(() => this.release());
-			});
-		});
-	}
-	release() {
-		const next = this.waiters.shift();
-		if (next) next();
-		else this.locked = false;
-	}
-	async runExclusive(fn) {
-		const release = await this.acquire();
-		try {
-			return await fn();
-		} finally {
-			release();
-		}
-	}
-	/** True iff someone holds the lock right now. Diagnostics only. */
-	get isLocked() {
-		return this.locked;
-	}
-	/** Pending waiter count. Diagnostics only. */
-	get pending() {
-		return this.waiters.length;
-	}
-};
-/** Map an integer range with bounded work, cancellation, and first-error cleanup. */
-async function mapConcurrentRange(options) {
-	if (!Number.isSafeInteger(options.count) || options.count < 0) throw new Error(`${options.label} count must be a non-negative integer`);
-	if (!Number.isSafeInteger(options.maxConcurrency) || options.maxConcurrency < 1) throw new Error(`${options.label} maxConcurrency must be a positive integer`);
-	const controller = new AbortController();
-	const abortFromCaller = () => controller.abort(options.signal?.reason);
-	if (options.signal?.aborted) abortFromCaller();
-	else options.signal?.addEventListener("abort", abortFromCaller, { once: true });
-	const results = new Array(options.count);
-	let nextIndex = 0;
-	let failed = false;
-	let firstFailure;
-	const workers = Array.from({ length: Math.min(options.maxConcurrency, options.count) }, async () => {
-		while (!controller.signal.aborted) {
-			const index = nextIndex;
-			nextIndex += 1;
-			if (index >= options.count) return;
-			try {
-				results[index] = await options.map(index, controller.signal);
-			} catch (error) {
-				if (!failed) {
-					failed = true;
-					firstFailure = error;
-					controller.abort(error);
-				}
-				return;
-			}
-		}
-	});
-	try {
-		await Promise.all(workers);
-		if (options.signal?.aborted) throw abortError(options.signal, options.label);
-		if (failed) throw firstFailure;
-		if (controller.signal.aborted) throw abortError(controller.signal, options.label);
-		return results;
-	} finally {
-		options.signal?.removeEventListener("abort", abortFromCaller);
-	}
-}
-/**
-* Map independent work with a fixed worker count while preserving input order.
-* After the first rejection, no new items start; already-running work is allowed
-* to settle before the returned promise rejects. Partial results are discarded.
-*/
-async function mapConcurrent(items, concurrency, map, signal) {
-	return mapConcurrentRange({
-		count: items.length,
-		maxConcurrency: concurrency,
-		label: "mapConcurrent",
-		signal,
-		map(index, signal) {
-			return map(items[index], index, signal);
-		}
-	});
-}
-function abortError(signal, label) {
-	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error(`${label} aborted`);
-}
-//#endregion
 //#region src/ledger-core/journal-file.ts
 /** Filesystem durability and cross-process exclusion for append-only journal files. */
 /** Append one already-serialized line; the write is fsynced (file and directory)
@@ -479,6 +372,113 @@ function fsyncDirectory(path) {
 	}
 }
 //#endregion
+//#region src/concurrency.ts
+/**
+* concurrency — small primitives the evolution loop needs.
+*
+* `Mutex` is a zero-dep async lock with FIFO fairness. The evolution loop
+* uses it to serialise checkout/build/commit sequences inside a single
+* pool slot, and to gate concurrent JSONL writers (see
+* `lockedJsonlReferenceReplayStore`).
+*
+* Deliberately minimal — no priority queue, no timeouts. If you need
+* those, swap to `async-mutex` at the call site.
+*/
+var Mutex = class {
+	locked = false;
+	waiters = [];
+	async acquire() {
+		if (!this.locked) {
+			this.locked = true;
+			return () => this.release();
+		}
+		return new Promise((resolve) => {
+			this.waiters.push(() => {
+				resolve(() => this.release());
+			});
+		});
+	}
+	release() {
+		const next = this.waiters.shift();
+		if (next) next();
+		else this.locked = false;
+	}
+	async runExclusive(fn) {
+		const release = await this.acquire();
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+	/** True iff someone holds the lock right now. Diagnostics only. */
+	get isLocked() {
+		return this.locked;
+	}
+	/** Pending waiter count. Diagnostics only. */
+	get pending() {
+		return this.waiters.length;
+	}
+};
+/** Map an integer range with bounded work, cancellation, and first-error cleanup. */
+async function mapConcurrentRange(options) {
+	if (!Number.isSafeInteger(options.count) || options.count < 0) throw new Error(`${options.label} count must be a non-negative integer`);
+	if (!Number.isSafeInteger(options.maxConcurrency) || options.maxConcurrency < 1) throw new Error(`${options.label} maxConcurrency must be a positive integer`);
+	const controller = new AbortController();
+	const abortFromCaller = () => controller.abort(options.signal?.reason);
+	if (options.signal?.aborted) abortFromCaller();
+	else options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+	const results = new Array(options.count);
+	let nextIndex = 0;
+	let failed = false;
+	let firstFailure;
+	const workers = Array.from({ length: Math.min(options.maxConcurrency, options.count) }, async () => {
+		while (!controller.signal.aborted) {
+			const index = nextIndex;
+			nextIndex += 1;
+			if (index >= options.count) return;
+			try {
+				results[index] = await options.map(index, controller.signal);
+			} catch (error) {
+				if (!failed) {
+					failed = true;
+					firstFailure = error;
+					controller.abort(error);
+				}
+				return;
+			}
+		}
+	});
+	try {
+		await Promise.all(workers);
+		if (options.signal?.aborted) throw abortError(options.signal, options.label);
+		if (failed) throw firstFailure;
+		if (controller.signal.aborted) throw abortError(controller.signal, options.label);
+		return results;
+	} finally {
+		options.signal?.removeEventListener("abort", abortFromCaller);
+	}
+}
+/**
+* Map independent work with a fixed worker count while preserving input order.
+* After the first rejection, no new items start; already-running work is allowed
+* to settle before the returned promise rejects. Partial results are discarded.
+*/
+async function mapConcurrent(items, concurrency, map, signal) {
+	return mapConcurrentRange({
+		count: items.length,
+		maxConcurrency: concurrency,
+		label: "mapConcurrent",
+		signal,
+		map(index, signal) {
+			return map(items[index], index, signal);
+		}
+	});
+}
+function abortError(signal, label) {
+	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error(`${label} aborted`);
+}
+//#endregion
 //#region src/ledger-core/projector-snapshot.ts
 /**
 * Projector snapshot — the cache that lets opening a large journal replay
@@ -1338,6 +1338,6 @@ function readRange(fd, start, end) {
 	return bytes;
 }
 //#endregion
-export { probeAtomicFileLock as _, trustedHeadPathFor as a, readProjectorSnapshotFile as c, withLedgerFileLock as d, writeLedgerFileAtomically as f, AtomicFileLockError as g, mapConcurrentRange as h, readTrustedHeadFile as i, appendLedgerLine as l, mapConcurrent as m, MemoryLedgerJournal as n, verifyEntriesAgainstTrustedHead as o, Mutex as p, replayLedgerText as r, projectorSnapshotPathFor as s, FileLedgerJournal as t, tryWithLedgerFileLock as u, tryAcquireAtomicFileLock as v };
+export { mapConcurrent as a, tryWithLedgerFileLock as c, probeAtomicFileLock as d, tryAcquireAtomicFileLock as f, Mutex as i, withLedgerFileLock as l, MemoryLedgerJournal as n, mapConcurrentRange as o, replayLedgerText as r, appendLedgerLine as s, FileLedgerJournal as t, writeLedgerFileAtomically as u };
 
-//# sourceMappingURL=journal-DvKCvjty.js.map
+//# sourceMappingURL=journal-CR4QikYp.js.map