@tangle-network/agent-eval 0.215.1 → 0.216.1

package/dist/interval-CELpye1n.js

@@ -0,0 +1,219 @@
+import { s as ValidationError } from "./errors-DVZiqS7K.js";
+import { t as mulberry32 } from "./random-ByUSnV9w.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-CELpye1n.js.map

package/dist/interval-CELpye1n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interval-CELpye1n.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-DfRz9kps.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-B2RqLofv.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";
@@ -1340,4 +1340,4 @@ function readRange(fd, start, end) {
 //#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 };
 
-//# sourceMappingURL=journal-DvKCvjty.js.map
+//# sourceMappingURL=journal-DfRz9kps.js.map