@tangle-network/agent-eval 1.0.19 → 1.0.21

package/dist/paired-arms-DjMEtYI9.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paired-arms-DjMEtYI9.js","names":[],"sources":["../src/arm-populations.ts","../src/paired-arms.ts"],"sourcesContent":["import type { FindingTreatment } from './analyst/finding-composition'\nimport { findingTreatmentSchema } from './analyst/finding-composition'\nimport type { PairedArmRow } from './paired-arms'\n\n/** Expected seed identities must be supplied independently of completed observations. */\nexport interface ArmAssignment {\n  pairKey: string\n  repKey?: string\n  arm: string\n  treatment?: FindingTreatment[]\n}\nexport interface ArmPopulationSummary {\n  n: number\n  passed: number\n  failed: number\n  missingOutcomes: number\n  /** Unknown unless every unit's outcome was observed; missing is never a failed check. */\n  passRate: number | null\n  metrics: Record<string, { n: number; missing: number; sum: number | null; mean: number | null }>\n}\nexport interface ArmPopulationReading {\n  arm: string\n  assignments: ArmAssignment[]\n  missingObservations: number\n  formation: { formed: number; notFormed: number; unknown: number }\n  asAssigned: ArmPopulationSummary\n  asFormed: ArmPopulationSummary\n}\n\nconst keyOf = (row: ArmAssignment): string =>\n  JSON.stringify([row.arm, row.pairKey, row.repKey ?? null])\nfunction checkIdentity(row: ArmAssignment): void {\n  for (const value of [row.arm, row.pairKey, ...(row.repKey === undefined ? [] : [row.repKey])]) {\n    if (typeof value !== 'string' || !value.trim())\n      throw new TypeError('Arm assignments require nonempty identities')\n  }\n  if (row.treatment !== undefined) {\n    if (!Array.isArray(row.treatment)) throw new TypeError('Arm treatment must be an array')\n    for (const value of row.treatment) findingTreatmentSchema.parse(value)\n    if (new Set(row.treatment.map((t) => t.id)).size !== row.treatment.length)\n      throw new TypeError('Duplicate arm treatment id')\n  }\n}\nfunction checkObservation(row: PairedArmRow): void {\n  checkIdentity(row)\n  if (row.pass != null && typeof row.pass !== 'boolean')\n    throw new TypeError('Invalid arm pass value')\n  if (row.formation !== undefined) {\n    if (row.formation === null || typeof row.formation !== 'object')\n      throw new TypeError('Invalid formation verdict')\n    if (row.formation.formed !== null && typeof row.formation.formed !== 'boolean')\n      throw new TypeError('Invalid formation state')\n    if (row.formation.reason !== undefined && typeof row.formation.reason !== 'string')\n      throw new TypeError('Invalid formation reason')\n  }\n  for (const value of Object.values(row.metrics ?? {})) {\n    if (value !== null && !Number.isFinite(value)) throw new TypeError('Non-finite arm metric')\n  }\n}\n\n/** One roster join serves comparison and both denominators; no outcomes are inferred from formation. */\nexport function prepareArmPopulations(\n  observations: readonly PairedArmRow[],\n  assignments: readonly ArmAssignment[],\n  options: { baselineArm: string; treatmentArm: string; metricNames?: string[] },\n): { rows: PairedArmRow[]; readings: ArmPopulationReading[] } {\n  const arms = [options.baselineArm, options.treatmentArm]\n  const roster = new Map<string, ArmAssignment>()\n  for (const entry of assignments) {\n    if (!arms.includes(entry.arm)) continue\n    checkIdentity(entry)\n    const key = keyOf(entry)\n    if (roster.has(key)) throw new TypeError('Duplicate arm assignment')\n    roster.set(key, structuredClone(entry))\n  }\n  for (const arm of arms)\n    if (![...roster.values()].some((r) => r.arm === arm))\n      throw new TypeError(`No assignment roster for arm '${arm}'`)\n  const actual = new Map<string, PairedArmRow>()\n  for (const row of observations) {\n    if (!arms.includes(row.arm)) continue\n    checkObservation(row)\n    const key = keyOf(row)\n    if (!roster.has(key)) throw new TypeError('Observed seed is outside the assignment roster')\n    if (actual.has(key)) throw new TypeError('Duplicate arm observation')\n    actual.set(key, row)\n  }\n  const ordered = [...roster.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n  // Placeholder rows carry identities only. They never manufacture pass, metrics or formation.\n  const rows = ordered.map(([key, entry]) => actual.get(key) ?? entry)\n  const metricNames =\n    options.metricNames ??\n    [...new Set([...actual.values()].flatMap((r) => Object.keys(r.metrics ?? {})))].sort()\n  const readings = arms.map((arm) => {\n    const declared = ordered.filter(([, r]) => r.arm === arm)\n    const asAssigned = declared.map(([key]) => actual.get(key))\n    const asFormed = asAssigned.filter(\n      (row): row is PairedArmRow => row?.formation?.formed === true,\n    )\n    return {\n      arm,\n      assignments: declared.map(([, r]) => r),\n      missingObservations: asAssigned.filter((r) => r === undefined).length,\n      formation: {\n        formed: asFormed.length,\n        notFormed: asAssigned.filter((r) => r?.formation?.formed === false).length,\n        unknown: asAssigned.filter((r) => r?.formation?.formed == null).length,\n      },\n      asAssigned: summarize(asAssigned, metricNames),\n      asFormed: summarize(asFormed, metricNames),\n    }\n  })\n  return { rows, readings }\n}\n\nfunction summarize(\n  rows: readonly (PairedArmRow | undefined)[],\n  names: readonly string[],\n): ArmPopulationSummary {\n  const passed = rows.filter((r) => r?.pass === true).length\n  const failed = rows.filter((r) => r?.pass === false).length\n  const missingOutcomes = rows.length - passed - failed\n  const metrics = Object.fromEntries(\n    names.map((name) => {\n      const values = rows.map((r) => r?.metrics?.[name]).filter((x): x is number => x != null)\n      const sum = values.length ? values.reduce((s, v) => s + v, 0) : null\n      return [\n        name,\n        {\n          n: values.length,\n          missing: rows.length - values.length,\n          sum,\n          mean: sum === null ? null : sum / values.length,\n        },\n      ]\n    }),\n  )\n  return {\n    n: rows.length,\n    passed,\n    failed,\n    missingOutcomes,\n    passRate: rows.length && !missingOutcomes ? passed / rows.length : null,\n    metrics,\n  }\n}\n","/**\n * Matched-pair arm comparison — \"did the treatment arm beat the baseline arm\n * on the SAME work items?\"\n *\n * An arm A/B over run records is only trustworthy when it is PAIRED: the same\n * task/scenario/seed evaluated under both arms, compared item-by-item, so\n * inter-item difficulty variance cancels instead of masquerading as an arm\n * effect. This module owns the two error-prone steps every consumer otherwise\n * hand-rolls:\n *\n *   1. Pairing — matching rows across arms by `pairKey` (and by `repKey`\n *      within multi-rep items), with leftovers REPORTED rather than silently\n *      dropped (a silently unbalanced pairing biases every paired statistic\n *      downstream). Pairing never keys on outcome content: matching reps by\n *      their outcomes deflates discordant-pair counts and makes McNemar\n *      anti-conservative, so reps pair only by (`pairKey`, `repKey`) identity.\n *   2. Composition — feeding the matched pairs to the correct paired\n *      estimators that already live in `statistics`: `mcnemar` +\n *      `pairedRiskDifference` for pass/fail, `pairedBootstrap` +\n *      `wilcoxonSignedRank` for continuous metrics. No statistic is\n *      re-implemented here.\n *\n * The row shape is deliberately structural — callers project a `RunRecord`\n * (or any record) into `{ pairKey, arm, pass?, metrics? }`. Arm names are\n * caller-supplied parameters; the module ships no domain literal.\n */\n\nimport type { FindingTreatment } from './analyst/finding-composition'\nimport {\n  type ArmAssignment,\n  type ArmPopulationReading,\n  prepareArmPopulations,\n} from './arm-populations'\nimport { ValidationError } from './errors'\nimport type { RunRecord } from './run-record'\nimport type { McNemarResult, PairedBootstrapOptions, PairedBootstrapResult } from './statistics'\nimport {\n  mcnemar,\n  pairedBootstrap,\n  pairedRiskDifference,\n  type RiskDifferenceResult,\n  wilcoxonSignedRank,\n} from './statistics'\n\n/** One arm observation of one work item. Structural on purpose: callers\n *  project their own record type (e.g. a `RunRecord`) into this shape. */\nexport interface PairedArmRow {\n  /** Matching key — rows sharing a `pairKey` across both arms form pairs\n   *  (typically the task/scenario/seed identity). */\n  pairKey: string\n  /** Rep identity within a `pairKey` (e.g. a seed or rep number). Required on\n   *  every row of a `pairKey` that has more than one rep in either arm; reps\n   *  then pair only on exact (`pairKey`, `repKey`) match, never on outcome\n   *  content. Optional when each arm has at most one rep of the item. */\n  repKey?: string\n  /** Arm label this row was produced under. */\n  arm: string\n  /** Binary outcome; omit or null when no pass/fail outcome was observed. */\n  pass?: boolean | null\n  /** Actual formation verdict from the execution owner; absence/null stays unknown. */\n  formation?: { formed: boolean | null; reason?: string }\n  /** Recorded treatment provenance; assigned bundles live on the independent roster. */\n  treatment?: FindingTreatment[]\n  /** Named finite measurements; null/absent readings are unknown, not zero. */\n  metrics?: Record<string, number | null>\n}\n\nexport interface PairArmsOptions {\n  /** Arm treated as the control side of every pair. */\n  baselineArm: string\n  /** Arm treated as the treatment side of every pair. */\n  treatmentArm: string\n}\n\n/** One matched (baseline, treatment) observation of the same work item. */\nexport interface MatchedPair {\n  pairKey: string\n  /** 0-based position of this pair within its `pairKey`, ordered by sorted\n   *  `repKey` (always 0 for a single-rep item). The rep identity itself is on\n   *  the rows (`baseline.repKey` / `treatment.repKey`). */\n  repIndex: number\n  baseline: PairedArmRow\n  treatment: PairedArmRow\n}\n\nexport interface PairArmsResult {\n  /** Matched pairs, ordered by (`pairKey`, `repIndex`). */\n  pairs: MatchedPair[]\n  /** Baseline rows left without a treatment counterpart — reported, never\n   *  silently dropped. */\n  unpairedBaseline: PairedArmRow[]\n  /** Treatment rows left without a baseline counterpart. */\n  unpairedTreatment: PairedArmRow[]\n}\n\n/**\n * Match rows across two arms into (baseline, treatment) pairs by `pairKey`.\n *\n * A `pairKey` with at most one row per arm pairs directly, no `repKey`\n * needed. A `pairKey` with multiple reps in either arm requires `repKey` on\n * every one of its rows, and reps pair only on exact (`pairKey`, `repKey`)\n * match — pairing is keyed purely on row identity, never on outcome content\n * (outcome-keyed matching deflates discordant counts and biases McNemar), and\n * is therefore independent of input order. Reps whose `repKey` has no\n * counterpart in the other arm, and items present in only one arm, land in\n * the unpaired lists — reported, never truncated.\n *\n * Fail-loud: throws when either named arm has zero rows (an unknown arm\n * name would otherwise read as \"everything unpaired\"), when the two arm\n * names are equal, when a multi-rep `pairKey` has a row without `repKey`, or\n * when a (`pairKey`, arm) group repeats a `repKey` (the match would be\n * ambiguous).\n */\nexport function pairArms(rows: readonly PairedArmRow[], opts: PairArmsOptions): PairArmsResult {\n  const { baselineArm, treatmentArm } = opts\n  if (baselineArm === treatmentArm) {\n    throw new ValidationError(\n      `pairArms: baselineArm and treatmentArm are both '${baselineArm}' — an arm cannot be compared to itself`,\n    )\n  }\n\n  // arm → pairKey → rows\n  const byArm = new Map<string, Map<string, PairedArmRow[]>>()\n  const armsSeen = new Set<string>()\n  for (const row of rows) {\n    armsSeen.add(row.arm)\n    if (row.arm !== baselineArm && row.arm !== treatmentArm) continue\n    const byKey = byArm.get(row.arm) ?? new Map<string, PairedArmRow[]>()\n    const group = byKey.get(row.pairKey) ?? []\n    group.push(row)\n    byKey.set(row.pairKey, group)\n    byArm.set(row.arm, byKey)\n  }\n\n  for (const arm of [baselineArm, treatmentArm]) {\n    if (!byArm.has(arm)) {\n      const seen = [...armsSeen].sort().join(', ') || '<none>'\n      throw new ValidationError(`pairArms: no rows for arm '${arm}' (arms present: ${seen})`)\n    }\n  }\n\n  const baselineByKey = byArm.get(baselineArm)!\n  const treatmentByKey = byArm.get(treatmentArm)!\n\n  const allKeys = [...new Set([...baselineByKey.keys(), ...treatmentByKey.keys()])].sort()\n  const pairs: MatchedPair[] = []\n  const unpairedBaseline: PairedArmRow[] = []\n  const unpairedTreatment: PairedArmRow[] = []\n  for (const pairKey of allKeys) {\n    const b = baselineByKey.get(pairKey) ?? []\n    const t = treatmentByKey.get(pairKey) ?? []\n\n    if (b.length <= 1 && t.length <= 1) {\n      if (b.length === 1 && t.length === 1) {\n        const baseline = b[0]!\n        const treatment = t[0]!\n        if (baseline.repKey !== undefined || treatment.repKey !== undefined) {\n          if (\n            baseline.repKey === undefined ||\n            treatment.repKey === undefined ||\n            baseline.repKey !== treatment.repKey\n          ) {\n            unpairedBaseline.push(baseline)\n            unpairedTreatment.push(treatment)\n            continue\n          }\n        }\n        pairs.push({ pairKey, repIndex: 0, baseline, treatment })\n      } else {\n        unpairedBaseline.push(...b)\n        unpairedTreatment.push(...t)\n      }\n      continue\n    }\n\n    const bByRep = indexByRepKey(b, pairKey, baselineArm)\n    const tByRep = indexByRepKey(t, pairKey, treatmentArm)\n    const repKeys = [...new Set([...bByRep.keys(), ...tByRep.keys()])].sort()\n    let repIndex = 0\n    for (const repKey of repKeys) {\n      const baseline = bByRep.get(repKey)\n      const treatment = tByRep.get(repKey)\n      if (baseline !== undefined && treatment !== undefined) {\n        pairs.push({ pairKey, repIndex: repIndex++, baseline, treatment })\n      } else if (baseline !== undefined) {\n        unpairedBaseline.push(baseline)\n      } else if (treatment !== undefined) {\n        unpairedTreatment.push(treatment)\n      }\n    }\n  }\n\n  return { pairs, unpairedBaseline, unpairedTreatment }\n}\n\n/** Index a multi-rep (pairKey, arm) group by `repKey`, enforcing that every\n *  row carries one and that no repKey repeats within the group. */\nfunction indexByRepKey(\n  group: readonly PairedArmRow[],\n  pairKey: string,\n  arm: string,\n): Map<string, PairedArmRow> {\n  const byRep = new Map<string, PairedArmRow>()\n  for (const row of group) {\n    if (row.repKey === undefined) {\n      throw new ValidationError(\n        `pairArms: pairKey '${pairKey}' has multiple reps in an arm, but a row in arm '${arm}' ` +\n          `is missing repKey — multi-rep items require an explicit repKey on every row so reps ` +\n          `pair by identity (pairing reps by outcome or by index would bias the paired statistics)`,\n      )\n    }\n    if (byRep.has(row.repKey)) {\n      throw new ValidationError(\n        `pairArms: duplicate repKey '${row.repKey}' for pairKey '${pairKey}' in arm '${arm}' — ` +\n          `(pairKey, repKey) must uniquely identify a rep within an arm`,\n      )\n    }\n    byRep.set(row.repKey, row)\n  }\n  return byRep\n}\n\n/** Paired pass/fail comparison over the pairs where BOTH sides carry `pass`. */\nexport interface PairedCorrectness {\n  /** Discordant pairs where the treatment passed and the baseline failed. */\n  b10: number\n  /** Discordant pairs where the baseline passed and the treatment failed. */\n  b01: number\n  /** Exact McNemar significance over the paired outcomes (`b === b10`, `c === b01`). */\n  mcnemar: McNemarResult\n  /** Paired effect size: p(treatment) − p(baseline) with a paired-variance CI. */\n  riskDifference: RiskDifferenceResult\n}\n\n/** Paired delta summary for one named metric (delta = treatment − baseline). */\nexport interface PairedMetricDelta {\n  name: string\n  /** Pairs where BOTH sides carry a finite value for this metric. */\n  n: number\n  /** Pairs where at least one side does not carry the metric. */\n  nMissing: number\n  /** Median paired delta, or null when `n === 0`. */\n  medianDelta: number | null\n  /** Mean paired delta, or null when `n === 0`. */\n  meanDelta: number | null\n  /** Bootstrap CI on the paired delta (`pairedBootstrap`); null when\n   *  `n === 0` — a zero-width [0, 0] interval on no data would read as a\n   *  measured tight null. */\n  bootstrapCi: PairedBootstrapResult | null\n  /** Wilcoxon signed-rank test on the paired deltas; null when `n === 0`. */\n  wilcoxon: { w: number; p: number } | null\n}\n\nexport interface ComparePairedArmsOptions extends PairArmsOptions {\n  /** Supply all expected seeds to report as-assigned and as-formed populations. */\n  assignments?: readonly ArmAssignment[]\n  /** Metrics to compare. Default: every metric name observed on any matched\n   *  pair, sorted. A name that appears on no pair is still reported (with\n   *  `n = 0`) so a misspelled metric is visible instead of vanishing. */\n  metricNames?: string[]\n  /** Passed through to `pairedBootstrap` — set `seed` for reproducible CIs. */\n  bootstrap?: PairedBootstrapOptions\n}\n\nexport interface PairedArmsComparison {\n  /** Absent when the assignment population is unknown (no roster supplied). */\n  armPopulations?: ArmPopulationReading[]\n  nPairs: number\n  nUnpairedBaseline: number\n  nUnpairedTreatment: number\n  /** null when no matched pair carries `pass` on both sides — a pass/fail\n   *  verdict over rows that never measured pass/fail would be fabricated. */\n  correctness: PairedCorrectness | null\n  metricDeltas: PairedMetricDelta[]\n}\n\n/**\n * Full matched-pair arm comparison: pair via {@link pairArms}, then compose\n * the paired estimators from `statistics` over the matched pairs.\n *\n * Correctness uses only the pairs where both sides carry `pass` (`mcnemar.n`\n * is that subset's size); each metric uses only the pairs where both sides\n * carry a finite value for it, with the remainder counted in `nMissing`.\n * Deltas are treatment − baseline throughout. With an assignment roster, pairing\n * covers declared seed identities; missing observations remain identity-only rows\n * and never contribute fabricated outcomes or metrics. Per-arm summaries report\n * every assignment and the explicitly formed subset separately.\n *\n * Fail-loud: inherits {@link pairArms}'s unknown-arm throw, and throws on a\n * non-finite metric value — silently treating corrupt telemetry as \"metric\n * absent\" would misreport it as missing coverage.\n */\nexport function comparePairedArms(\n  rows: readonly PairedArmRow[],\n  opts: ComparePairedArmsOptions,\n): PairedArmsComparison {\n  const populations =\n    opts.assignments === undefined ? undefined : prepareArmPopulations(rows, opts.assignments, opts)\n  const { pairs, unpairedBaseline, unpairedTreatment } = pairArms(populations?.rows ?? rows, opts)\n\n  let correctness: PairedCorrectness | null = null\n  const baselinePass: number[] = []\n  const treatmentPass: number[] = []\n  for (const pair of pairs) {\n    if (pair.baseline.pass == null || pair.treatment.pass == null) continue\n    baselinePass.push(pair.baseline.pass ? 1 : 0)\n    treatmentPass.push(pair.treatment.pass ? 1 : 0)\n  }\n  if (baselinePass.length > 0) {\n    const mc = mcnemar(baselinePass, treatmentPass)\n    correctness = {\n      b10: mc.b,\n      b01: mc.c,\n      mcnemar: mc,\n      riskDifference: pairedRiskDifference(baselinePass, treatmentPass),\n    }\n  }\n\n  const metricNames =\n    opts.metricNames ??\n    [\n      ...new Set(\n        pairs.flatMap((p) => [\n          ...Object.keys(p.baseline.metrics ?? {}),\n          ...Object.keys(p.treatment.metrics ?? {}),\n        ]),\n      ),\n    ].sort()\n\n  const metricDeltas: PairedMetricDelta[] = metricNames.map((name) => {\n    const before: number[] = []\n    const after: number[] = []\n    let nMissing = 0\n    for (const pair of pairs) {\n      const b = metricValue(pair.baseline, name)\n      const t = metricValue(pair.treatment, name)\n      if (b === undefined || t === undefined) {\n        nMissing++\n        continue\n      }\n      before.push(b)\n      after.push(t)\n    }\n    const bootstrapCi = before.length === 0 ? null : pairedBootstrap(before, after, opts.bootstrap)\n    return {\n      name,\n      n: before.length,\n      nMissing,\n      medianDelta: bootstrapCi?.median ?? null,\n      meanDelta: bootstrapCi?.mean ?? null,\n      bootstrapCi,\n      wilcoxon: before.length === 0 ? null : wilcoxonSignedRank(before, after),\n    }\n  })\n\n  return {\n    ...(populations ? { armPopulations: populations.readings } : {}),\n    nPairs: pairs.length,\n    nUnpairedBaseline: unpairedBaseline.length,\n    nUnpairedTreatment: unpairedTreatment.length,\n    correctness,\n    metricDeltas,\n  }\n}\n\nexport interface MatchedRunRecordPair {\n  pairKey: string\n  repKey: string\n  baseline: RunRecord\n  treatment: RunRecord\n}\n\nexport interface PairRunRecordsResult {\n  pairs: MatchedRunRecordPair[]\n  unpairedBaseline: RunRecord[]\n  unpairedTreatment: RunRecord[]\n}\n\ninterface RunRecordArmRow extends PairedArmRow {\n  run: RunRecord\n  repKey: string\n}\n\n/**\n * Pair two RunRecord arms by the identity of the evaluated work:\n * `(experimentId, scenarioId, seed)`.\n *\n * Falling back to array order, candidate id, or experiment id can compare\n * different tasks and fabricate lift. Duplicate identities throw.\n */\nexport function pairRunRecords(\n  baselineRuns: readonly RunRecord[],\n  treatmentRuns: readonly RunRecord[],\n): PairRunRecordsResult {\n  const baselineRows = runRecordArmRows(baselineRuns, 'baseline')\n  const treatmentRows = runRecordArmRows(treatmentRuns, 'treatment')\n  validateRunRecordArmRows(baselineRows, 'baseline')\n  validateRunRecordArmRows(treatmentRows, 'treatment')\n  if (baselineRows.length === 0 || treatmentRows.length === 0) {\n    return {\n      pairs: [],\n      unpairedBaseline: baselineRows.map((row) => row.run),\n      unpairedTreatment: treatmentRows.map((row) => row.run),\n    }\n  }\n\n  const result = pairArms([...baselineRows, ...treatmentRows], {\n    baselineArm: 'baseline',\n    treatmentArm: 'treatment',\n  })\n  return {\n    pairs: result.pairs.map((pair) => {\n      const baseline = pair.baseline as RunRecordArmRow\n      const treatment = pair.treatment as RunRecordArmRow\n      return {\n        pairKey: pair.pairKey,\n        repKey: baseline.repKey,\n        baseline: baseline.run,\n        treatment: treatment.run,\n      }\n    }),\n    unpairedBaseline: result.unpairedBaseline.map((row) => (row as RunRecordArmRow).run),\n    unpairedTreatment: result.unpairedTreatment.map((row) => (row as RunRecordArmRow).run),\n  }\n}\n\nfunction runRecordArmRows(runs: readonly RunRecord[], arm: string): RunRecordArmRow[] {\n  return runs.map((run) => {\n    const scenarioId = run.scenarioId.trim()\n    if (!scenarioId) {\n      throw new ValidationError(\n        `pairRunRecords: run '${run.runId}' is missing scenarioId; paired comparisons require explicit scenario identity`,\n      )\n    }\n    return {\n      pairKey: JSON.stringify([run.experimentId, scenarioId]),\n      repKey: String(run.seed),\n      arm,\n      run,\n    }\n  })\n}\n\nfunction validateRunRecordArmRows(rows: readonly RunRecordArmRow[], arm: string): void {\n  const byPairKey = new Map<string, RunRecordArmRow[]>()\n  for (const row of rows) {\n    const group = byPairKey.get(row.pairKey) ?? []\n    group.push(row)\n    byPairKey.set(row.pairKey, group)\n  }\n  for (const [pairKey, group] of byPairKey) {\n    if (group.length > 1) indexByRepKey(group, pairKey, arm)\n  }\n}\n\nfunction metricValue(row: PairedArmRow, name: string): number | undefined {\n  const v = row.metrics?.[name]\n  if (v == null) return undefined\n  if (!Number.isFinite(v)) {\n    throw new ValidationError(\n      `comparePairedArms: non-finite value for metric '${name}' on pairKey '${row.pairKey}' (arm '${row.arm}'): ${v}`,\n    )\n  }\n  return v\n}\n"],"mappings":"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"}

package/dist/{paired-promotion-decision-CiueaTTj.js → paired-promotion-decision-Bi9__RQS.js}

@@ -1,5 +1,4 @@
-import { a as pairedRiskDifferenceScore, i as pairedRiskDifferenceExact, n as pairedBinaryScale } from "./paired-binary-CMzmSSd5.js";
-import { a as pairedSignTest, i as pairedDeltaTieFraction, r as pairedBootstrap } from "./paired-tests-Buh6feJ4.js";
+import { S as pairedRiskDifferenceScore, h as pairedSignTest, m as pairedDeltaTieFraction, p as pairedBootstrap, x as pairedRiskDifferenceExact, y as pairedBinaryScale } from "./statistics-CvvC-MPv.js";
 // src/paired-delta-test.ts
 /** Smallest all-positive sample that can clear a one-sided exact sign test. */
 function minimumPairsForPairedDeltaTest(confidence = .95) {
@@ -253,4 +252,4 @@ function fmt(x) {
 }
 export { pairedDeltaTest as i, pairedDecisionShape as n, minimumPairsForPairedDeltaTest as r, decidePairedPromotion as t };
 
-//# sourceMappingURL=paired-promotion-decision-CiueaTTj.js.map
+//# sourceMappingURL=paired-promotion-decision-Bi9__RQS.js.map

package/dist/{paired-promotion-decision-CiueaTTj.js.map → paired-promotion-decision-Bi9__RQS.js.map}

@@ -1 +1 @@
-{"version":3,"file":"paired-promotion-decision-CiueaTTj.js","names":[],"sources":["../src/paired-delta-test.ts","../src/paired-promotion-decision.ts"],"sourcesContent":["import {\n  type PairedBootstrapOptions,\n  type PairedBootstrapResult,\n  pairedBootstrap,\n  pairedSignTest,\n} from './statistics'\n\nexport interface PairedDeltaTestOptions extends PairedBootstrapOptions {\n  /** Smallest candidate-minus-baseline delta that counts as improvement. Default 0. */\n  threshold?: number\n  /** Caller-required paired observations. The exact test may impose a higher minimum. */\n  minPairs?: number\n}\n\nexport interface PairedDeltaTestResult {\n  bootstrap: PairedBootstrapResult\n  method: 'bootstrap-ci' | 'exact-sign'\n  /** Exact one-sided p-value below the bootstrap minimum; otherwise null. */\n  pValue: number | null\n  /** Effective observation minimum after accounting for confidence. */\n  minimumPairs: number\n  sufficient: boolean\n  /**\n   * The bootstrap interval has zero width (or is non-finite), so it carries no\n   * information about how far the estimate could be wrong and cannot support a\n   * decision in either direction. See {@link pairedDeltaTest}.\n   */\n  indeterminate: boolean\n  significant: boolean\n}\n\n/** Smallest all-positive sample that can clear a one-sided exact sign test. */\nexport function minimumPairsForPairedDeltaTest(confidence = 0.95): number {\n  if (!Number.isFinite(confidence) || confidence <= 0 || confidence >= 1) {\n    throw new Error(\n      `minimumPairsForPairedDeltaTest: confidence must be in (0,1), got ${confidence}`,\n    )\n  }\n  const oneSidedAlpha = (1 - confidence) / 2\n  return Math.ceil(Math.log2(1 / oneSidedAlpha))\n}\n\n/**\n * Tests whether a paired candidate-minus-baseline delta clears a threshold.\n *\n * At 20 or more pairs, the percentile bootstrap lower bound carries the\n * decision. Below that point the interval is descriptive only, so the function\n * switches to a pre-registered one-sided exact sign test. The exact path is\n * deliberately conservative: it requires both a point estimate above the\n * threshold and enough consistently positive paired differences.\n *\n * ## A zero-width interval is never significant\n *\n * When every paired delta is identical the resample distribution is a point\n * mass and the interval collapses: `[0, 0]` when all pairs tie, `[g, g]` on n\n * identical deltas of g. Neither says the effect is certain — both say the\n * sample carries no information about how far the estimate could be wrong, and\n * `low > threshold` then answers on the point estimate alone. It fails in both\n * directions: `[0, 0]` clears every NEGATIVE threshold, which is how a\n * tie-dominated pass/fail comparison laundered a regression into a\n * noninferiority pass, and `[g, g]` clears every threshold below g with no\n * spread behind it. Under a bounded asymmetric null whose true mean paired\n * delta is exactly 0 — 2 % of pairs dropping by 1.0, the rest gaining 0.0204 —\n * every sample that misses the drop is exactly that shape, and deciding on\n * `low > 0` promoted 65.65 % of samples at n = 20 against a nominal 5 %.\n *\n * So `indeterminate` is reported and `significant` is false whenever the\n * interval has zero width, on BOTH paths: at small n the exact sign test is a\n * test of the MEDIAN and a zero-spread sample is precisely where it stops\n * saying anything about the mean the caller is thresholding.\n *\n * `threshold` may be negative — that is a noninferiority margin, and it is the\n * regime the zero-width hole is worst in. For a two-point (pass/fail) outcome\n * the percentile bootstrap is not a valid interval at a nonzero margin at all;\n * use {@link decidePairedPromotion}, which routes those to Tango's score\n * interval, rather than thresholding this function's bootstrap directly.\n */\nexport function pairedDeltaTest(\n  before: number[],\n  after: number[],\n  options: PairedDeltaTestOptions = {},\n): PairedDeltaTestResult {\n  const threshold = options.threshold ?? 0\n  if (!Number.isFinite(threshold)) {\n    throw new Error(`pairedDeltaTest: threshold must be finite, got ${threshold}`)\n  }\n  const confidence = options.confidence ?? 0.95\n  const exactMinimum = minimumPairsForPairedDeltaTest(confidence)\n  const requestedMinimum = options.minPairs ?? exactMinimum\n  if (!Number.isInteger(requestedMinimum) || requestedMinimum < 1) {\n    throw new Error(`pairedDeltaTest: minPairs must be a positive integer, got ${requestedMinimum}`)\n  }\n  const minimumPairs = Math.max(requestedMinimum, exactMinimum)\n  const bootstrap = pairedBootstrap(before, after, options)\n  const sufficient = bootstrap.n >= minimumPairs\n  // A point-mass resample distribution is an absence of evidence, not a\n  // certainty, and it is the shape that clears every negative threshold. Both\n  // paths refuse it: see the \"zero-width\" section of this function's docs.\n  const indeterminate =\n    bootstrap.n > 0 &&\n    (!Number.isFinite(bootstrap.low) ||\n      !Number.isFinite(bootstrap.high) ||\n      bootstrap.low === bootstrap.high)\n\n  if (bootstrap.gateEligible) {\n    return {\n      bootstrap,\n      method: 'bootstrap-ci',\n      pValue: null,\n      minimumPairs,\n      sufficient,\n      indeterminate,\n      significant: sufficient && !indeterminate && bootstrap.low > threshold,\n    }\n  }\n\n  const differences = before.map((value, index) => after[index]! - value - threshold)\n  const exact = pairedSignTest(differences, 'greater')\n  const estimate = options.statistic === 'mean' ? bootstrap.mean : bootstrap.median\n  return {\n    bootstrap,\n    method: 'exact-sign',\n    pValue: exact.pValue,\n    minimumPairs,\n    sufficient,\n    indeterminate,\n    significant:\n      sufficient &&\n      !indeterminate &&\n      estimate > threshold &&\n      exact.pValue <= (1 - bootstrap.confidence) / 2,\n  }\n}\n","/**\n * @module\n * ONE rule for \"does this paired interval clear a promotion threshold\".\n *\n * The rule below was derived on `HeldOutGate` (#479) after the same estimator\n * bug shipped twice. It then turned out that a SECOND gate — the composable\n * `heldOutGate`, plus everything else routed through `heldoutSignificance` —\n * still carried the original defect, because the rule had been written into one\n * gate's method body rather than into a shared function. Two copies of a\n * statistical rule is how a defect survives in one of them, so there is now\n * exactly one copy and both gates call it.\n *\n * Three things the rule does that a bare `pairedBootstrap(...).low > threshold`\n * does not:\n *\n * 1. **Two-point (pass/fail) outcomes decide on Tango's SCORE interval.** On a\n *    pass/fail eval the paired delta vector is dominated by ties, so the\n *    bootstrap of the mean is a resample of a lattice with three atoms and its\n *    percentile interval is not valid at a nonzero margin. The score interval\n *    (`pairedRiskDifferenceScore`) re-estimates the nuisance loss rate under\n *    each hypothesised margin instead of fixing it at the observed value, which\n *    is the only construction that stays a confidence interval as the margin\n *    moves off zero — the regime every noninferiority threshold lives in.\n *    Measured on the composable gate before this change, at a true risk\n *    difference sitting exactly on the production caller's -0.05 margin and a\n *    nominal 5 %: 14.60 % false promotion at n = 40 and 10.10 % at n = 76.\n * 2. **McNemar's exact test holds a VETO at every non-negative threshold.**\n *    Redundant with the interval by construction and kept anyway, so that\n *    swapping the estimator for one without that duality cannot silently\n *    reintroduce \"promotes what the exact test refuses\". Witness: n = 6, b = 5,\n *    c = 0 — no exact argument reaches alpha = 0.05 with 5 discordant pairs\n *    (two-sided floor 2/2^5 = 0.0625), whatever an interval says. A NEGATIVE\n *    threshold is a noninferiority question, which McNemar's test of \"no\n *    difference\" is not the right test for, so the veto does not apply there.\n * 3. **A ZERO-WIDTH interval is refused, wherever it sits.** At [0, 0] it\n *    cannot tell a gain from a regression and clears every negative threshold.\n *    Away from zero it fails the opposite way: n identical positive deltas give\n *    [g, g], which clears threshold 0 on no spread at all. Both are an absence\n *    of evidence. Measured on the composable gate before this change, under a\n *    bounded asymmetric null whose true mean paired delta is exactly 0: 88.50 %\n *    false promotion at n = 6 and 65.65 % at n = 20 against a nominal 5 %.\n *\n * Eligibility follows the requested target. A continuous mean needs the\n * bootstrap minimum; binary outcomes and explicit median targets use the\n * exact-test minimum. A small-sample sign diagnostic cannot certify a mean\n * effect. These floors establish estimator eligibility, not adequate power.\n */\n\nimport { minimumPairsForPairedDeltaTest, pairedDeltaTest } from './paired-delta-test'\nimport {\n  BOOTSTRAP_GATE_MIN_N,\n  type PairedBootstrapResult,\n  pairedBinaryScale,\n  pairedDeltaTieFraction,\n  pairedRiskDifferenceExact,\n  pairedRiskDifferenceScore,\n} from './statistics'\n\n/** Which paired estimator produced the deciding interval. */\nexport type PairedDecisionStatistic =\n  | 'paired_risk_difference'\n  | 'mean_bootstrap'\n  | 'median_bootstrap'\n\n/** Which test carried the decision, given the estimator and the sample size. */\nexport type PairedDecisionMethod = 'score-interval' | 'bootstrap-ci' | 'exact-sign'\n\n/** McNemar's exact paired-binary evidence, on the two-point path only. */\nexport interface PairedMcNemarEvidence {\n  /** Discordant pairs the treatment won. */\n  b: number\n  /** Discordant pairs the control won. */\n  c: number\n  /** b + c — the only pairs carrying information. */\n  nDiscordant: number\n  /** Two-sided exact p-value. */\n  pValue: number\n}\n\nexport interface PairedPromotionDecisionOptions {\n  /** Smallest candidate-minus-baseline delta that counts as improvement, in the\n   *  caller's native units. May be negative (a noninferiority margin). Default 0. */\n  threshold?: number\n  /** Confidence level. Default 0.95. */\n  confidence?: number\n  /** Bootstrap resamples, on the paths where a bootstrap decides. Default 2000. */\n  resamples?: number\n  /** Deterministic bootstrap seed. Omitted ⇒ derived from the deltas. */\n  seed?: number\n  /** Caller-required paired observations. The test also imposes its own\n   *  minimum: bootstrap eligibility for a continuous mean, or the exact-test\n   *  minimum for binary and explicit median targets. This is not a power guarantee. */\n  minPairs?: number\n  /**\n   * `'mean'` (default) routes by SHAPE: a two-point (pass/fail) outcome on any\n   * encoding decides on the score interval, everything else on the mean\n   * bootstrap. `'median'` forces the median bootstrap on every input, including\n   * shapes where it is structurally blind — kept for callers who want outlier\n   * robustness on genuinely continuous outcomes and accept that cost.\n   */\n  statistic?: 'mean' | 'median'\n  /** Declared binary support {0, binaryScale}, including when all observations\n   *  are zero. Must be finite and positive; every observation must use that\n   *  support. Uses the risk-difference mean, so cannot accompany 'median'.\n   *  Omitted: infer binary support from observed positive values. */\n  binaryScale?: number\n  /**\n   * Declare the outcome continuous: never infer a two-point support from the\n   * observed values, so the estimator is fixed before the data is seen. A\n   * sealed call on a continuous measure must route to the bootstrap whatever\n   * the sample happens to look like; with inference on, a sample whose values\n   * all land on {0, s} is silently decided on the score interval instead.\n   * Measured under discovery's E1 alternative (deltas in {+1, -0.5, 0} on a\n   * zero baseline) at 20 pairs: 5.4 % of 2,000 simulated samples (seed 11)\n   * re-route without this flag, 0 with it; the exact rate is 5.54 %\n   * (`paired-promotion-power.test.ts`). Cannot accompany `binaryScale`.\n   */\n  continuous?: boolean\n}\n\nexport interface PairedPromotionDecision {\n  /** Paired observations supplied. */\n  n: number\n  /** Threshold the interval was judged against, native units. */\n  threshold: number\n  confidence: number\n  statistic: PairedDecisionStatistic\n  method: PairedDecisionMethod\n  /** Declared or inferred positive level ({0,1} ⇒ 1, {0,100} ⇒ 100),\n   *  or null when the outcome is not two-point. Non-null is exactly the\n   *  condition for the `paired_risk_difference` path, and it is the factor\n   *  `delta` / `low` / `high` were rescaled by. */\n  binaryScale: number | null\n  /** Exact-tie fraction over the paired deltas; null when there are no pairs. */\n  tieFraction: number | null\n  /** Point estimate of the DECIDING statistic, in the caller's native units. */\n  delta: number\n  /** Lower bound of the DECIDING interval, native units. */\n  low: number\n  /** Upper bound of the DECIDING interval, native units. */\n  high: number\n  /** The bootstrap that decided, or null when the score interval did. Callers\n   *  that need a bootstrap as a diagnostic on the two-point path compute their\n   *  own — it is not computed here, so the binary path costs no resamples. */\n  bootstrap: PairedBootstrapResult | null\n  /** McNemar's exact evidence, or null off the two-point path. */\n  mcnemar: PairedMcNemarEvidence | null\n  /** Exact one-sided sign-test p-value on the small-sample bootstrap path;\n   *  null otherwise. */\n  pValue: number | null\n  /** Effective observation minimum for the target, confidence, and caller floor. */\n  minimumPairs: number\n  /** n >= minimumPairs. */\n  sufficient: boolean\n  /** The deciding interval is zero-width at numeric precision or non-finite — no evidence in either\n   *  direction, so it cannot clear any threshold on evidence. */\n  indeterminate: boolean\n  /** McNemar's exact test refuses at a non-negative threshold. */\n  exactTestVetoes: boolean\n  /** The deciding interval clears the threshold, ignoring the other two guards. */\n  clearsThreshold: boolean\n  /** `sufficient && !indeterminate && clearsThreshold && !exactTestVetoes` —\n   *  the whole rule. */\n  promote: boolean\n  /** What `delta` measures, for a reason string. */\n  label: 'success-rate' | 'mean' | 'median'\n  /** Why a zero-width interval is zero-width; empty when it is not. */\n  indeterminateCause: string\n  /** Sentence naming the test when the exact sign test decided; else empty. */\n  methodDetail: string\n}\n\n/** The shape facts that pick the estimator, without computing an interval. */\nexport interface PairedDecisionShape {\n  statistic: PairedDecisionStatistic\n  /** Declared or inferred positive binary level; null off the binary path. */\n  binaryScale: number | null\n  /** Exact-tie fraction over the paired deltas; null when there are no pairs. */\n  tieFraction: number | null\n}\n\n/**\n * Which estimator {@link decidePairedPromotion} would use on this data, and the\n * shape facts behind it — for callers that must report the shape on a path\n * where no interval is computed at all (an early rejection, or zero pairs).\n * Cheap: no bootstrap, no interval.\n */\nexport function pairedDecisionShape(\n  before: number[],\n  after: number[],\n  statistic: 'mean' | 'median' = 'mean',\n  declaredBinaryScale?: number,\n  continuous = false,\n): PairedDecisionShape {\n  if (continuous && declaredBinaryScale !== undefined) {\n    throw new Error('pairedDecisionShape: continuous cannot accompany binaryScale')\n  }\n  if (declaredBinaryScale !== undefined) {\n    if (!Number.isFinite(declaredBinaryScale) || declaredBinaryScale <= 0) {\n      throw new Error('pairedDecisionShape: binaryScale must be finite and positive')\n    }\n    if (statistic === 'median') {\n      throw new Error('pairedDecisionShape: binaryScale requires the mean statistic, not median')\n    }\n    for (const [name, arm] of [\n      ['before', before],\n      ['after', after],\n    ] as const) {\n      for (let i = 0; i < arm.length; i++) {\n        const value = arm[i]!\n        if (value !== 0 && value !== declaredBinaryScale) {\n          throw new Error(\n            `pairedDecisionShape: ${name}[${i}] must be 0 or binaryScale (${declaredBinaryScale}); got ${value}`,\n          )\n        }\n      }\n    }\n  }\n  const tieFraction = before.length === 0 ? null : pairedDeltaTieFraction(before, after)\n  if (statistic === 'median') {\n    return { statistic: 'median_bootstrap', binaryScale: null, tieFraction }\n  }\n  if (continuous) {\n    return { statistic: 'mean_bootstrap', binaryScale: null, tieFraction }\n  }\n  const binaryScale = declaredBinaryScale ?? pairedBinaryScale(before, after)\n  if (binaryScale !== null) {\n    return { statistic: 'paired_risk_difference', binaryScale, tieFraction }\n  }\n  return { statistic: 'mean_bootstrap', binaryScale: null, tieFraction }\n}\n\n/**\n * Decide whether a paired candidate-minus-baseline delta clears a promotion\n * threshold. `before` is the baseline arm, `after` the candidate arm, paired by\n * position. Throws on unequal lengths.\n */\nexport function decidePairedPromotion(\n  before: number[],\n  after: number[],\n  options: PairedPromotionDecisionOptions = {},\n): PairedPromotionDecision {\n  if (before.length !== after.length) {\n    throw new Error(\n      `decidePairedPromotion: unequal sample sizes (${before.length} vs ${after.length})`,\n    )\n  }\n  const threshold = options.threshold ?? 0\n  if (!Number.isFinite(threshold)) {\n    throw new Error(`decidePairedPromotion: threshold must be finite, got ${threshold}`)\n  }\n  const confidence = options.confidence ?? 0.95\n  const exactMinimum = minimumPairsForPairedDeltaTest(confidence)\n  const requestedMinimum = options.minPairs ?? exactMinimum\n  if (!Number.isInteger(requestedMinimum) || requestedMinimum < 1) {\n    throw new Error(\n      `decidePairedPromotion: minPairs must be a positive integer, got ${requestedMinimum}`,\n    )\n  }\n  const { binaryScale, tieFraction } = pairedDecisionShape(\n    before,\n    after,\n    options.statistic,\n    options.binaryScale,\n    options.continuous ?? false,\n  )\n  const estimatorMinimum =\n    binaryScale === null && options.statistic !== 'median' ? BOOTSTRAP_GATE_MIN_N : exactMinimum\n  const minimumPairs = Math.max(requestedMinimum, exactMinimum, estimatorMinimum)\n  const n = before.length\n  const sufficient = n >= minimumPairs\n\n  let core: {\n    statistic: PairedDecisionStatistic\n    method: PairedDecisionMethod\n    delta: number\n    low: number\n    high: number\n    bootstrap: PairedBootstrapResult | null\n    mcnemar: PairedMcNemarEvidence | null\n    pValue: number | null\n    clearsThreshold: boolean\n    label: PairedPromotionDecision['label']\n    methodDetail: string\n  }\n\n  if (binaryScale !== null) {\n    // Normalise the two-point encoding to {0,1} so the estimators see the\n    // pass/fail structure, then rescale the answer back into the caller's\n    // native units — the threshold is read in the units of the scores, so a\n    // 0-100 pass/fail dimension must be gated in points, not in a rate.\n    const unitControl = before.map((v) => v / binaryScale)\n    const unitTreatment = after.map((v) => v / binaryScale)\n    // TWO estimators with different jobs, because no single one does both.\n    // `exact` is the authority on RD = 0 and supplies the veto; its\n    // Clopper-Pearson interval conditions on the discordant count and is\n    // therefore NOT a confidence interval at a nonzero margin. `score` is\n    // Tango's, which is.\n    const exact = pairedRiskDifferenceExact(unitControl, unitTreatment, confidence)\n    const score = pairedRiskDifferenceScore(unitControl, unitTreatment, confidence)\n    const low = score.lower * binaryScale\n    core = {\n      statistic: 'paired_risk_difference',\n      method: 'score-interval',\n      delta: score.riskDifference * binaryScale,\n      low,\n      high: score.upper * binaryScale,\n      bootstrap: null,\n      mcnemar: {\n        b: exact.b,\n        c: exact.c,\n        nDiscordant: exact.nDiscordant,\n        pValue: exact.pValue,\n      },\n      pValue: null,\n      clearsThreshold: low > threshold,\n      label: 'success-rate',\n      methodDetail: '',\n    }\n  } else {\n    const bootstrapStatistic = options.statistic === 'median' ? 'median' : 'mean'\n    const test = pairedDeltaTest(before, after, {\n      confidence,\n      resamples: options.resamples,\n      statistic: bootstrapStatistic,\n      seed: options.seed,\n      threshold,\n      minPairs: minimumPairs,\n    })\n    const ci = test.bootstrap\n    core = {\n      statistic: bootstrapStatistic === 'mean' ? 'mean_bootstrap' : 'median_bootstrap',\n      method: test.method,\n      delta: bootstrapStatistic === 'mean' ? ci.mean : ci.median,\n      low: ci.low,\n      high: ci.high,\n      bootstrap: ci,\n      mcnemar: null,\n      pValue: test.pValue,\n      clearsThreshold: test.significant,\n      label: bootstrapStatistic,\n      methodDetail:\n        test.method === 'exact-sign'\n          ? bootstrapStatistic === 'mean'\n            ? ` The mean requires ${minimumPairs} pairs for bootstrap eligibility;` +\n              ` the exact sign-test p=${fmt(test.pValue ?? 1)} does not establish a mean effect.`\n            : ` Below ${BOOTSTRAP_GATE_MIN_N} pairs the interval is descriptive only;` +\n              ` the median decision uses the exact one-sided sign test, p=${fmt(test.pValue ?? 1)}.`\n          : '',\n    }\n  }\n\n  // Equivalent deltas can differ by rounding after subtraction and averaging.\n  // Use the interval's own scale so tiny score units retain the same decision\n  // as a rescaled copy of the evidence.\n  const intervalScale = Math.max(Math.abs(core.low), Math.abs(core.high))\n  const intervalTolerance = intervalScale * Number.EPSILON * 8\n  const indeterminate =\n    !Number.isFinite(core.low) ||\n    !Number.isFinite(core.high) ||\n    core.high - core.low <= intervalTolerance\n  const indeterminateCause = !indeterminate\n    ? ''\n    : tieFraction === 1\n      ? 'every paired delta is an exact tie'\n      : core.mcnemar !== null && core.mcnemar.nDiscordant === 0\n        ? 'every pair is concordant (0 discordant pairs)'\n        : `the ${core.label} CI collapsed to a point at ${fmt(core.low)}`\n  // Only at a non-negative threshold: a negative threshold asks a\n  // noninferiority question, which McNemar's test of \"no difference\" does not\n  // answer.\n  const exactTestVetoes =\n    core.mcnemar !== null && threshold >= 0 && !(core.mcnemar.pValue < 1 - confidence)\n\n  return {\n    n,\n    threshold,\n    confidence,\n    binaryScale,\n    tieFraction,\n    minimumPairs,\n    sufficient,\n    indeterminate,\n    indeterminateCause,\n    exactTestVetoes,\n    promote: sufficient && !indeterminate && core.clearsThreshold && !exactTestVetoes,\n    ...core,\n  }\n}\n\nfunction fmt(x: number): string {\n  return x.toFixed(4)\n}\n"],"mappings":";;;;AAgCA,SAAgB,+BAA+B,aAAa,KAAc;CACxE,IAAI,CAAC,OAAO,SAAS,UAAU,KAAK,cAAc,KAAK,cAAc,GACnE,MAAM,IAAI,MACR,oEAAoE,YACtE;CAEF,MAAM,iBAAiB,IAAI,cAAc;CACzC,OAAO,KAAK,KAAK,KAAK,KAAK,IAAI,aAAa,CAAC;AAC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,gBACd,QACA,OACA,UAAkC,CAAC,GACZ;CACvB,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI,CAAC,OAAO,SAAS,SAAS,GAC5B,MAAM,IAAI,MAAM,kDAAkD,WAAW;CAG/E,MAAM,eAAe,+BADF,QAAQ,cAAc,GACqB;CAC9D,MAAM,mBAAmB,QAAQ,YAAY;CAC7C,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC5D,MAAM,IAAI,MAAM,6DAA6D,kBAAkB;CAEjG,MAAM,eAAe,KAAK,IAAI,kBAAkB,YAAY;CAC5D,MAAM,YAAY,gBAAgB,QAAQ,OAAO,OAAO;CACxD,MAAM,aAAa,UAAU,KAAK;CAIlC,MAAM,gBACJ,UAAU,IAAI,MACb,CAAC,OAAO,SAAS,UAAU,GAAG,KAC7B,CAAC,OAAO,SAAS,UAAU,IAAI,KAC/B,UAAU,QAAQ,UAAU;CAEhC,IAAI,UAAU,cACZ,OAAO;EACL;EACA,QAAQ;EACR,QAAQ;EACR;EACA;EACA;EACA,aAAa,cAAc,CAAC,iBAAiB,UAAU,MAAM;CAC/D;CAGF,MAAM,cAAc,OAAO,KAAK,OAAO,UAAU,MAAM,SAAU,QAAQ,SAAS;CAClF,MAAM,QAAQ,eAAe,aAAa,SAAS;CACnD,MAAM,WAAW,QAAQ,cAAc,SAAS,UAAU,OAAO,UAAU;CAC3E,OAAO;EACL;EACA,QAAQ;EACR,QAAQ,MAAM;EACd;EACA;EACA;EACA,aACE,cACA,CAAC,iBACD,WAAW,aACX,MAAM,WAAW,IAAI,UAAU,cAAc;CACjD;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACuDA,SAAgB,oBACd,QACA,OACA,YAA+B,QAC/B,qBACA,aAAa,OACQ;CACrB,IAAI,cAAc,wBAAwB,KAAA,GACxC,MAAM,IAAI,MAAM,8DAA8D;CAEhF,IAAI,wBAAwB,KAAA,GAAW;EACrC,IAAI,CAAC,OAAO,SAAS,mBAAmB,KAAK,uBAAuB,GAClE,MAAM,IAAI,MAAM,8DAA8D;EAEhF,IAAI,cAAc,UAChB,MAAM,IAAI,MAAM,0EAA0E;EAE5F,KAAK,MAAM,CAAC,MAAM,QAAQ,CACxB,CAAC,UAAU,MAAM,GACjB,CAAC,SAAS,KAAK,CACjB,GACE,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;GACnC,MAAM,QAAQ,IAAI;GAClB,IAAI,UAAU,KAAK,UAAU,qBAC3B,MAAM,IAAI,MACR,wBAAwB,KAAK,GAAG,EAAE,8BAA8B,oBAAoB,SAAS,OAC/F;EAEJ;CAEJ;CACA,MAAM,cAAc,OAAO,WAAW,IAAI,OAAO,uBAAuB,QAAQ,KAAK;CACrF,IAAI,cAAc,UAChB,OAAO;EAAE,WAAW;EAAoB,aAAa;EAAM;CAAY;CAEzE,IAAI,YACF,OAAO;EAAE,WAAW;EAAkB,aAAa;EAAM;CAAY;CAEvE,MAAM,cAAc,uBAAuB,kBAAkB,QAAQ,KAAK;CAC1E,IAAI,gBAAgB,MAClB,OAAO;EAAE,WAAW;EAA0B;EAAa;CAAY;CAEzE,OAAO;EAAE,WAAW;EAAkB,aAAa;EAAM;CAAY;AACvE;;;;;;AAOA,SAAgB,sBACd,QACA,OACA,UAA0C,CAAC,GAClB;CACzB,IAAI,OAAO,WAAW,MAAM,QAC1B,MAAM,IAAI,MACR,gDAAgD,OAAO,OAAO,MAAM,MAAM,OAAO,EACnF;CAEF,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI,CAAC,OAAO,SAAS,SAAS,GAC5B,MAAM,IAAI,MAAM,wDAAwD,WAAW;CAErF,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,eAAe,+BAA+B,UAAU;CAC9D,MAAM,mBAAmB,QAAQ,YAAY;CAC7C,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC5D,MAAM,IAAI,MACR,mEAAmE,kBACrE;CAEF,MAAM,EAAE,aAAa,gBAAgB,oBACnC,QACA,OACA,QAAQ,WACR,QAAQ,aACR,QAAQ,cAAc,KACxB;CACA,MAAM,mBACJ,gBAAgB,QAAQ,QAAQ,cAAc,WAAA,KAAkC;CAClF,MAAM,eAAe,KAAK,IAAI,kBAAkB,cAAc,gBAAgB;CAC9E,MAAM,IAAI,OAAO;CACjB,MAAM,aAAa,KAAK;CAExB,IAAI;CAcJ,IAAI,gBAAgB,MAAM;EAKxB,MAAM,cAAc,OAAO,KAAK,MAAM,IAAI,WAAW;EACrD,MAAM,gBAAgB,MAAM,KAAK,MAAM,IAAI,WAAW;EAMtD,MAAM,QAAQ,0BAA0B,aAAa,eAAe,UAAU;EAC9E,MAAM,QAAQ,0BAA0B,aAAa,eAAe,UAAU;EAC9E,MAAM,MAAM,MAAM,QAAQ;EAC1B,OAAO;GACL,WAAW;GACX,QAAQ;GACR,OAAO,MAAM,iBAAiB;GAC9B;GACA,MAAM,MAAM,QAAQ;GACpB,WAAW;GACX,SAAS;IACP,GAAG,MAAM;IACT,GAAG,MAAM;IACT,aAAa,MAAM;IACnB,QAAQ,MAAM;GAChB;GACA,QAAQ;GACR,iBAAiB,MAAM;GACvB,OAAO;GACP,cAAc;EAChB;CACF,OAAO;EACL,MAAM,qBAAqB,QAAQ,cAAc,WAAW,WAAW;EACvE,MAAM,OAAO,gBAAgB,QAAQ,OAAO;GAC1C;GACA,WAAW,QAAQ;GACnB,WAAW;GACX,MAAM,QAAQ;GACd;GACA,UAAU;EACZ,CAAC;EACD,MAAM,KAAK,KAAK;EAChB,OAAO;GACL,WAAW,uBAAuB,SAAS,mBAAmB;GAC9D,QAAQ,KAAK;GACb,OAAO,uBAAuB,SAAS,GAAG,OAAO,GAAG;GACpD,KAAK,GAAG;GACR,MAAM,GAAG;GACT,WAAW;GACX,SAAS;GACT,QAAQ,KAAK;GACb,iBAAiB,KAAK;GACtB,OAAO;GACP,cACE,KAAK,WAAW,eACZ,uBAAuB,SACrB,sBAAsB,aAAa,0DACT,IAAI,KAAK,UAAU,CAAC,EAAE,sCAChD,+GAC8D,IAAI,KAAK,UAAU,CAAC,EAAE,KACtF;EACR;CACF;CAMA,MAAM,oBADgB,KAAK,IAAI,KAAK,IAAI,KAAK,GAAG,GAAG,KAAK,IAAI,KAAK,IAAI,CAC/B,IAAI,OAAO,UAAU;CAC3D,MAAM,gBACJ,CAAC,OAAO,SAAS,KAAK,GAAG,KACzB,CAAC,OAAO,SAAS,KAAK,IAAI,KAC1B,KAAK,OAAO,KAAK,OAAO;CAC1B,MAAM,qBAAqB,CAAC,gBACxB,KACA,gBAAgB,IACd,uCACA,KAAK,YAAY,QAAQ,KAAK,QAAQ,gBAAgB,IACpD,kDACA,OAAO,KAAK,MAAM,8BAA8B,IAAI,KAAK,GAAG;CAIpE,MAAM,kBACJ,KAAK,YAAY,QAAQ,aAAa,KAAK,EAAE,KAAK,QAAQ,SAAS,IAAI;CAEzE,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,SAAS,cAAc,CAAC,iBAAiB,KAAK,mBAAmB,CAAC;EAClE,GAAG;CACL;AACF;AAEA,SAAS,IAAI,GAAmB;CAC9B,OAAO,EAAE,QAAQ,CAAC;AACpB"}
+{"version":3,"file":"paired-promotion-decision-Bi9__RQS.js","names":[],"sources":["../src/paired-delta-test.ts","../src/paired-promotion-decision.ts"],"sourcesContent":["import {\n  type PairedBootstrapOptions,\n  type PairedBootstrapResult,\n  pairedBootstrap,\n  pairedSignTest,\n} from './statistics'\n\nexport interface PairedDeltaTestOptions extends PairedBootstrapOptions {\n  /** Smallest candidate-minus-baseline delta that counts as improvement. Default 0. */\n  threshold?: number\n  /** Caller-required paired observations. The exact test may impose a higher minimum. */\n  minPairs?: number\n}\n\nexport interface PairedDeltaTestResult {\n  bootstrap: PairedBootstrapResult\n  method: 'bootstrap-ci' | 'exact-sign'\n  /** Exact one-sided p-value below the bootstrap minimum; otherwise null. */\n  pValue: number | null\n  /** Effective observation minimum after accounting for confidence. */\n  minimumPairs: number\n  sufficient: boolean\n  /**\n   * The bootstrap interval has zero width (or is non-finite), so it carries no\n   * information about how far the estimate could be wrong and cannot support a\n   * decision in either direction. See {@link pairedDeltaTest}.\n   */\n  indeterminate: boolean\n  significant: boolean\n}\n\n/** Smallest all-positive sample that can clear a one-sided exact sign test. */\nexport function minimumPairsForPairedDeltaTest(confidence = 0.95): number {\n  if (!Number.isFinite(confidence) || confidence <= 0 || confidence >= 1) {\n    throw new Error(\n      `minimumPairsForPairedDeltaTest: confidence must be in (0,1), got ${confidence}`,\n    )\n  }\n  const oneSidedAlpha = (1 - confidence) / 2\n  return Math.ceil(Math.log2(1 / oneSidedAlpha))\n}\n\n/**\n * Tests whether a paired candidate-minus-baseline delta clears a threshold.\n *\n * At 20 or more pairs, the percentile bootstrap lower bound carries the\n * decision. Below that point the interval is descriptive only, so the function\n * switches to a pre-registered one-sided exact sign test. The exact path is\n * deliberately conservative: it requires both a point estimate above the\n * threshold and enough consistently positive paired differences.\n *\n * ## A zero-width interval is never significant\n *\n * When every paired delta is identical the resample distribution is a point\n * mass and the interval collapses: `[0, 0]` when all pairs tie, `[g, g]` on n\n * identical deltas of g. Neither says the effect is certain — both say the\n * sample carries no information about how far the estimate could be wrong, and\n * `low > threshold` then answers on the point estimate alone. It fails in both\n * directions: `[0, 0]` clears every NEGATIVE threshold, which is how a\n * tie-dominated pass/fail comparison laundered a regression into a\n * noninferiority pass, and `[g, g]` clears every threshold below g with no\n * spread behind it. Under a bounded asymmetric null whose true mean paired\n * delta is exactly 0 — 2 % of pairs dropping by 1.0, the rest gaining 0.0204 —\n * every sample that misses the drop is exactly that shape, and deciding on\n * `low > 0` promoted 65.65 % of samples at n = 20 against a nominal 5 %.\n *\n * So `indeterminate` is reported and `significant` is false whenever the\n * interval has zero width, on BOTH paths: at small n the exact sign test is a\n * test of the MEDIAN and a zero-spread sample is precisely where it stops\n * saying anything about the mean the caller is thresholding.\n *\n * `threshold` may be negative — that is a noninferiority margin, and it is the\n * regime the zero-width hole is worst in. For a two-point (pass/fail) outcome\n * the percentile bootstrap is not a valid interval at a nonzero margin at all;\n * use {@link decidePairedPromotion}, which routes those to Tango's score\n * interval, rather than thresholding this function's bootstrap directly.\n */\nexport function pairedDeltaTest(\n  before: number[],\n  after: number[],\n  options: PairedDeltaTestOptions = {},\n): PairedDeltaTestResult {\n  const threshold = options.threshold ?? 0\n  if (!Number.isFinite(threshold)) {\n    throw new Error(`pairedDeltaTest: threshold must be finite, got ${threshold}`)\n  }\n  const confidence = options.confidence ?? 0.95\n  const exactMinimum = minimumPairsForPairedDeltaTest(confidence)\n  const requestedMinimum = options.minPairs ?? exactMinimum\n  if (!Number.isInteger(requestedMinimum) || requestedMinimum < 1) {\n    throw new Error(`pairedDeltaTest: minPairs must be a positive integer, got ${requestedMinimum}`)\n  }\n  const minimumPairs = Math.max(requestedMinimum, exactMinimum)\n  const bootstrap = pairedBootstrap(before, after, options)\n  const sufficient = bootstrap.n >= minimumPairs\n  // A point-mass resample distribution is an absence of evidence, not a\n  // certainty, and it is the shape that clears every negative threshold. Both\n  // paths refuse it: see the \"zero-width\" section of this function's docs.\n  const indeterminate =\n    bootstrap.n > 0 &&\n    (!Number.isFinite(bootstrap.low) ||\n      !Number.isFinite(bootstrap.high) ||\n      bootstrap.low === bootstrap.high)\n\n  if (bootstrap.gateEligible) {\n    return {\n      bootstrap,\n      method: 'bootstrap-ci',\n      pValue: null,\n      minimumPairs,\n      sufficient,\n      indeterminate,\n      significant: sufficient && !indeterminate && bootstrap.low > threshold,\n    }\n  }\n\n  const differences = before.map((value, index) => after[index]! - value - threshold)\n  const exact = pairedSignTest(differences, 'greater')\n  const estimate = options.statistic === 'mean' ? bootstrap.mean : bootstrap.median\n  return {\n    bootstrap,\n    method: 'exact-sign',\n    pValue: exact.pValue,\n    minimumPairs,\n    sufficient,\n    indeterminate,\n    significant:\n      sufficient &&\n      !indeterminate &&\n      estimate > threshold &&\n      exact.pValue <= (1 - bootstrap.confidence) / 2,\n  }\n}\n","/**\n * @module\n * ONE rule for \"does this paired interval clear a promotion threshold\".\n *\n * The rule below was derived on `HeldOutGate` (#479) after the same estimator\n * bug shipped twice. It then turned out that a SECOND gate — the composable\n * `heldOutGate`, plus everything else routed through `heldoutSignificance` —\n * still carried the original defect, because the rule had been written into one\n * gate's method body rather than into a shared function. Two copies of a\n * statistical rule is how a defect survives in one of them, so there is now\n * exactly one copy and both gates call it.\n *\n * Three things the rule does that a bare `pairedBootstrap(...).low > threshold`\n * does not:\n *\n * 1. **Two-point (pass/fail) outcomes decide on Tango's SCORE interval.** On a\n *    pass/fail eval the paired delta vector is dominated by ties, so the\n *    bootstrap of the mean is a resample of a lattice with three atoms and its\n *    percentile interval is not valid at a nonzero margin. The score interval\n *    (`pairedRiskDifferenceScore`) re-estimates the nuisance loss rate under\n *    each hypothesised margin instead of fixing it at the observed value, which\n *    is the only construction that stays a confidence interval as the margin\n *    moves off zero — the regime every noninferiority threshold lives in.\n *    Measured on the composable gate before this change, at a true risk\n *    difference sitting exactly on the production caller's -0.05 margin and a\n *    nominal 5 %: 14.60 % false promotion at n = 40 and 10.10 % at n = 76.\n * 2. **McNemar's exact test holds a VETO at every non-negative threshold.**\n *    Redundant with the interval by construction and kept anyway, so that\n *    swapping the estimator for one without that duality cannot silently\n *    reintroduce \"promotes what the exact test refuses\". Witness: n = 6, b = 5,\n *    c = 0 — no exact argument reaches alpha = 0.05 with 5 discordant pairs\n *    (two-sided floor 2/2^5 = 0.0625), whatever an interval says. A NEGATIVE\n *    threshold is a noninferiority question, which McNemar's test of \"no\n *    difference\" is not the right test for, so the veto does not apply there.\n * 3. **A ZERO-WIDTH interval is refused, wherever it sits.** At [0, 0] it\n *    cannot tell a gain from a regression and clears every negative threshold.\n *    Away from zero it fails the opposite way: n identical positive deltas give\n *    [g, g], which clears threshold 0 on no spread at all. Both are an absence\n *    of evidence. Measured on the composable gate before this change, under a\n *    bounded asymmetric null whose true mean paired delta is exactly 0: 88.50 %\n *    false promotion at n = 6 and 65.65 % at n = 20 against a nominal 5 %.\n *\n * Eligibility follows the requested target. A continuous mean needs the\n * bootstrap minimum; binary outcomes and explicit median targets use the\n * exact-test minimum. A small-sample sign diagnostic cannot certify a mean\n * effect. These floors establish estimator eligibility, not adequate power.\n */\n\nimport { minimumPairsForPairedDeltaTest, pairedDeltaTest } from './paired-delta-test'\nimport {\n  BOOTSTRAP_GATE_MIN_N,\n  type PairedBootstrapResult,\n  pairedBinaryScale,\n  pairedDeltaTieFraction,\n  pairedRiskDifferenceExact,\n  pairedRiskDifferenceScore,\n} from './statistics'\n\n/** Which paired estimator produced the deciding interval. */\nexport type PairedDecisionStatistic =\n  | 'paired_risk_difference'\n  | 'mean_bootstrap'\n  | 'median_bootstrap'\n\n/** Which test carried the decision, given the estimator and the sample size. */\nexport type PairedDecisionMethod = 'score-interval' | 'bootstrap-ci' | 'exact-sign'\n\n/** McNemar's exact paired-binary evidence, on the two-point path only. */\nexport interface PairedMcNemarEvidence {\n  /** Discordant pairs the treatment won. */\n  b: number\n  /** Discordant pairs the control won. */\n  c: number\n  /** b + c — the only pairs carrying information. */\n  nDiscordant: number\n  /** Two-sided exact p-value. */\n  pValue: number\n}\n\nexport interface PairedPromotionDecisionOptions {\n  /** Smallest candidate-minus-baseline delta that counts as improvement, in the\n   *  caller's native units. May be negative (a noninferiority margin). Default 0. */\n  threshold?: number\n  /** Confidence level. Default 0.95. */\n  confidence?: number\n  /** Bootstrap resamples, on the paths where a bootstrap decides. Default 2000. */\n  resamples?: number\n  /** Deterministic bootstrap seed. Omitted ⇒ derived from the deltas. */\n  seed?: number\n  /** Caller-required paired observations. The test also imposes its own\n   *  minimum: bootstrap eligibility for a continuous mean, or the exact-test\n   *  minimum for binary and explicit median targets. This is not a power guarantee. */\n  minPairs?: number\n  /**\n   * `'mean'` (default) routes by SHAPE: a two-point (pass/fail) outcome on any\n   * encoding decides on the score interval, everything else on the mean\n   * bootstrap. `'median'` forces the median bootstrap on every input, including\n   * shapes where it is structurally blind — kept for callers who want outlier\n   * robustness on genuinely continuous outcomes and accept that cost.\n   */\n  statistic?: 'mean' | 'median'\n  /** Declared binary support {0, binaryScale}, including when all observations\n   *  are zero. Must be finite and positive; every observation must use that\n   *  support. Uses the risk-difference mean, so cannot accompany 'median'.\n   *  Omitted: infer binary support from observed positive values. */\n  binaryScale?: number\n  /**\n   * Declare the outcome continuous: never infer a two-point support from the\n   * observed values, so the estimator is fixed before the data is seen. A\n   * sealed call on a continuous measure must route to the bootstrap whatever\n   * the sample happens to look like; with inference on, a sample whose values\n   * all land on {0, s} is silently decided on the score interval instead.\n   * Measured under discovery's E1 alternative (deltas in {+1, -0.5, 0} on a\n   * zero baseline) at 20 pairs: 5.4 % of 2,000 simulated samples (seed 11)\n   * re-route without this flag, 0 with it; the exact rate is 5.54 %\n   * (`paired-promotion-power.test.ts`). Cannot accompany `binaryScale`.\n   */\n  continuous?: boolean\n}\n\nexport interface PairedPromotionDecision {\n  /** Paired observations supplied. */\n  n: number\n  /** Threshold the interval was judged against, native units. */\n  threshold: number\n  confidence: number\n  statistic: PairedDecisionStatistic\n  method: PairedDecisionMethod\n  /** Declared or inferred positive level ({0,1} ⇒ 1, {0,100} ⇒ 100),\n   *  or null when the outcome is not two-point. Non-null is exactly the\n   *  condition for the `paired_risk_difference` path, and it is the factor\n   *  `delta` / `low` / `high` were rescaled by. */\n  binaryScale: number | null\n  /** Exact-tie fraction over the paired deltas; null when there are no pairs. */\n  tieFraction: number | null\n  /** Point estimate of the DECIDING statistic, in the caller's native units. */\n  delta: number\n  /** Lower bound of the DECIDING interval, native units. */\n  low: number\n  /** Upper bound of the DECIDING interval, native units. */\n  high: number\n  /** The bootstrap that decided, or null when the score interval did. Callers\n   *  that need a bootstrap as a diagnostic on the two-point path compute their\n   *  own — it is not computed here, so the binary path costs no resamples. */\n  bootstrap: PairedBootstrapResult | null\n  /** McNemar's exact evidence, or null off the two-point path. */\n  mcnemar: PairedMcNemarEvidence | null\n  /** Exact one-sided sign-test p-value on the small-sample bootstrap path;\n   *  null otherwise. */\n  pValue: number | null\n  /** Effective observation minimum for the target, confidence, and caller floor. */\n  minimumPairs: number\n  /** n >= minimumPairs. */\n  sufficient: boolean\n  /** The deciding interval is zero-width at numeric precision or non-finite — no evidence in either\n   *  direction, so it cannot clear any threshold on evidence. */\n  indeterminate: boolean\n  /** McNemar's exact test refuses at a non-negative threshold. */\n  exactTestVetoes: boolean\n  /** The deciding interval clears the threshold, ignoring the other two guards. */\n  clearsThreshold: boolean\n  /** `sufficient && !indeterminate && clearsThreshold && !exactTestVetoes` —\n   *  the whole rule. */\n  promote: boolean\n  /** What `delta` measures, for a reason string. */\n  label: 'success-rate' | 'mean' | 'median'\n  /** Why a zero-width interval is zero-width; empty when it is not. */\n  indeterminateCause: string\n  /** Sentence naming the test when the exact sign test decided; else empty. */\n  methodDetail: string\n}\n\n/** The shape facts that pick the estimator, without computing an interval. */\nexport interface PairedDecisionShape {\n  statistic: PairedDecisionStatistic\n  /** Declared or inferred positive binary level; null off the binary path. */\n  binaryScale: number | null\n  /** Exact-tie fraction over the paired deltas; null when there are no pairs. */\n  tieFraction: number | null\n}\n\n/**\n * Which estimator {@link decidePairedPromotion} would use on this data, and the\n * shape facts behind it — for callers that must report the shape on a path\n * where no interval is computed at all (an early rejection, or zero pairs).\n * Cheap: no bootstrap, no interval.\n */\nexport function pairedDecisionShape(\n  before: number[],\n  after: number[],\n  statistic: 'mean' | 'median' = 'mean',\n  declaredBinaryScale?: number,\n  continuous = false,\n): PairedDecisionShape {\n  if (continuous && declaredBinaryScale !== undefined) {\n    throw new Error('pairedDecisionShape: continuous cannot accompany binaryScale')\n  }\n  if (declaredBinaryScale !== undefined) {\n    if (!Number.isFinite(declaredBinaryScale) || declaredBinaryScale <= 0) {\n      throw new Error('pairedDecisionShape: binaryScale must be finite and positive')\n    }\n    if (statistic === 'median') {\n      throw new Error('pairedDecisionShape: binaryScale requires the mean statistic, not median')\n    }\n    for (const [name, arm] of [\n      ['before', before],\n      ['after', after],\n    ] as const) {\n      for (let i = 0; i < arm.length; i++) {\n        const value = arm[i]!\n        if (value !== 0 && value !== declaredBinaryScale) {\n          throw new Error(\n            `pairedDecisionShape: ${name}[${i}] must be 0 or binaryScale (${declaredBinaryScale}); got ${value}`,\n          )\n        }\n      }\n    }\n  }\n  const tieFraction = before.length === 0 ? null : pairedDeltaTieFraction(before, after)\n  if (statistic === 'median') {\n    return { statistic: 'median_bootstrap', binaryScale: null, tieFraction }\n  }\n  if (continuous) {\n    return { statistic: 'mean_bootstrap', binaryScale: null, tieFraction }\n  }\n  const binaryScale = declaredBinaryScale ?? pairedBinaryScale(before, after)\n  if (binaryScale !== null) {\n    return { statistic: 'paired_risk_difference', binaryScale, tieFraction }\n  }\n  return { statistic: 'mean_bootstrap', binaryScale: null, tieFraction }\n}\n\n/**\n * Decide whether a paired candidate-minus-baseline delta clears a promotion\n * threshold. `before` is the baseline arm, `after` the candidate arm, paired by\n * position. Throws on unequal lengths.\n */\nexport function decidePairedPromotion(\n  before: number[],\n  after: number[],\n  options: PairedPromotionDecisionOptions = {},\n): PairedPromotionDecision {\n  if (before.length !== after.length) {\n    throw new Error(\n      `decidePairedPromotion: unequal sample sizes (${before.length} vs ${after.length})`,\n    )\n  }\n  const threshold = options.threshold ?? 0\n  if (!Number.isFinite(threshold)) {\n    throw new Error(`decidePairedPromotion: threshold must be finite, got ${threshold}`)\n  }\n  const confidence = options.confidence ?? 0.95\n  const exactMinimum = minimumPairsForPairedDeltaTest(confidence)\n  const requestedMinimum = options.minPairs ?? exactMinimum\n  if (!Number.isInteger(requestedMinimum) || requestedMinimum < 1) {\n    throw new Error(\n      `decidePairedPromotion: minPairs must be a positive integer, got ${requestedMinimum}`,\n    )\n  }\n  const { binaryScale, tieFraction } = pairedDecisionShape(\n    before,\n    after,\n    options.statistic,\n    options.binaryScale,\n    options.continuous ?? false,\n  )\n  const estimatorMinimum =\n    binaryScale === null && options.statistic !== 'median' ? BOOTSTRAP_GATE_MIN_N : exactMinimum\n  const minimumPairs = Math.max(requestedMinimum, exactMinimum, estimatorMinimum)\n  const n = before.length\n  const sufficient = n >= minimumPairs\n\n  let core: {\n    statistic: PairedDecisionStatistic\n    method: PairedDecisionMethod\n    delta: number\n    low: number\n    high: number\n    bootstrap: PairedBootstrapResult | null\n    mcnemar: PairedMcNemarEvidence | null\n    pValue: number | null\n    clearsThreshold: boolean\n    label: PairedPromotionDecision['label']\n    methodDetail: string\n  }\n\n  if (binaryScale !== null) {\n    // Normalise the two-point encoding to {0,1} so the estimators see the\n    // pass/fail structure, then rescale the answer back into the caller's\n    // native units — the threshold is read in the units of the scores, so a\n    // 0-100 pass/fail dimension must be gated in points, not in a rate.\n    const unitControl = before.map((v) => v / binaryScale)\n    const unitTreatment = after.map((v) => v / binaryScale)\n    // TWO estimators with different jobs, because no single one does both.\n    // `exact` is the authority on RD = 0 and supplies the veto; its\n    // Clopper-Pearson interval conditions on the discordant count and is\n    // therefore NOT a confidence interval at a nonzero margin. `score` is\n    // Tango's, which is.\n    const exact = pairedRiskDifferenceExact(unitControl, unitTreatment, confidence)\n    const score = pairedRiskDifferenceScore(unitControl, unitTreatment, confidence)\n    const low = score.lower * binaryScale\n    core = {\n      statistic: 'paired_risk_difference',\n      method: 'score-interval',\n      delta: score.riskDifference * binaryScale,\n      low,\n      high: score.upper * binaryScale,\n      bootstrap: null,\n      mcnemar: {\n        b: exact.b,\n        c: exact.c,\n        nDiscordant: exact.nDiscordant,\n        pValue: exact.pValue,\n      },\n      pValue: null,\n      clearsThreshold: low > threshold,\n      label: 'success-rate',\n      methodDetail: '',\n    }\n  } else {\n    const bootstrapStatistic = options.statistic === 'median' ? 'median' : 'mean'\n    const test = pairedDeltaTest(before, after, {\n      confidence,\n      resamples: options.resamples,\n      statistic: bootstrapStatistic,\n      seed: options.seed,\n      threshold,\n      minPairs: minimumPairs,\n    })\n    const ci = test.bootstrap\n    core = {\n      statistic: bootstrapStatistic === 'mean' ? 'mean_bootstrap' : 'median_bootstrap',\n      method: test.method,\n      delta: bootstrapStatistic === 'mean' ? ci.mean : ci.median,\n      low: ci.low,\n      high: ci.high,\n      bootstrap: ci,\n      mcnemar: null,\n      pValue: test.pValue,\n      clearsThreshold: test.significant,\n      label: bootstrapStatistic,\n      methodDetail:\n        test.method === 'exact-sign'\n          ? bootstrapStatistic === 'mean'\n            ? ` The mean requires ${minimumPairs} pairs for bootstrap eligibility;` +\n              ` the exact sign-test p=${fmt(test.pValue ?? 1)} does not establish a mean effect.`\n            : ` Below ${BOOTSTRAP_GATE_MIN_N} pairs the interval is descriptive only;` +\n              ` the median decision uses the exact one-sided sign test, p=${fmt(test.pValue ?? 1)}.`\n          : '',\n    }\n  }\n\n  // Equivalent deltas can differ by rounding after subtraction and averaging.\n  // Use the interval's own scale so tiny score units retain the same decision\n  // as a rescaled copy of the evidence.\n  const intervalScale = Math.max(Math.abs(core.low), Math.abs(core.high))\n  const intervalTolerance = intervalScale * Number.EPSILON * 8\n  const indeterminate =\n    !Number.isFinite(core.low) ||\n    !Number.isFinite(core.high) ||\n    core.high - core.low <= intervalTolerance\n  const indeterminateCause = !indeterminate\n    ? ''\n    : tieFraction === 1\n      ? 'every paired delta is an exact tie'\n      : core.mcnemar !== null && core.mcnemar.nDiscordant === 0\n        ? 'every pair is concordant (0 discordant pairs)'\n        : `the ${core.label} CI collapsed to a point at ${fmt(core.low)}`\n  // Only at a non-negative threshold: a negative threshold asks a\n  // noninferiority question, which McNemar's test of \"no difference\" does not\n  // answer.\n  const exactTestVetoes =\n    core.mcnemar !== null && threshold >= 0 && !(core.mcnemar.pValue < 1 - confidence)\n\n  return {\n    n,\n    threshold,\n    confidence,\n    binaryScale,\n    tieFraction,\n    minimumPairs,\n    sufficient,\n    indeterminate,\n    indeterminateCause,\n    exactTestVetoes,\n    promote: sufficient && !indeterminate && core.clearsThreshold && !exactTestVetoes,\n    ...core,\n  }\n}\n\nfunction fmt(x: number): string {\n  return x.toFixed(4)\n}\n"],"mappings":"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"}

package/dist/{paired-promotion-decision-BDnqepZ1.d.ts → paired-promotion-decision-DJU3fZxH.d.ts}

@@ -1,114 +1,4 @@
-/**
- * Paired significance tests on continuous scores: the paired t-test, the
- * promotion-gate paired bootstrap, the exact sign test, and the package-wide
- * paired-delta decision statistic.
- */
-interface PairedTTestResult {
-  /** Null when the statistic is undefined — see {@link pairedTTest}. */
-  t: number | null;
-  df: number;
-  /** Null exactly when `t` is null. */
-  p: number | null;
-}
-/**
- * Paired t-test — before/after measurements on the SAME items.
- * Pairing removes inter-item variance, giving tighter significance than
- * an unpaired test when comparing prompt v1 vs prompt v2 on identical
- * scenarios.
- *
- * Returns `t = p = null` where the statistic is undefined: fewer than two
- * pairs, or a non-zero constant delta whose observed variance is zero. A
- * constant shift carries no information about the variance it would have to
- * be compared against, so the honest answer is "undefined", not `p = 0` —
- * three observations cannot buy absolute certainty. This is the same contract
- * {@link pairedCohensDz} states for the same condition. An all-zero delta is
- * different: it is a measured null, and returns `t = 0, p = 1`.
- */
-declare function pairedTTest(before: number[], after: number[]): PairedTTestResult;
-interface PairedBootstrapResult {
-  /** Number of paired observations. */
-  n: number;
-  /** Median of paired deltas (after − before). */
-  median: number;
-  /** Mean of paired deltas. */
-  mean: number;
-  /** Lower bound of the bootstrap CI on the chosen statistic. */
-  low: number;
-  /** Upper bound of the bootstrap CI on the chosen statistic. */
-  high: number;
-  /** Confidence level used (e.g. 0.95). */
-  confidence: number;
-  /** Number of bootstrap resamples used. */
-  resamples: number;
-  /** False below {@link BOOTSTRAP_GATE_MIN_N}. See {@link pairedBootstrap}. */
-  gateEligible: boolean;
-}
-/**
- * Pairs below which a percentile bootstrap interval is descriptive spread only.
- *
- * `P(low > 0)` under a true null, against a nominal 2.5 %, measured over 4000
- * seeded trials: 13.53 % at n = 3, 3.52 % at n = 10, 3.10 % at n = 20 on the
- * median; 13.85 %, 4.90 %, 3.80 % on the mean. This is intrinsic to resampling
- * three points, not an implementation error — scipy's BCa gives 16.0 % on the
- * same n = 3 data — so no change to the estimator moves it. Below this floor
- * the decision belongs to the exact sign test or exact signed-rank test.
- */
-declare const BOOTSTRAP_GATE_MIN_N = 20;
-interface PairedBootstrapOptions {
-  /** Confidence level. Default 0.95. */
-  confidence?: number;
-  /** Bootstrap resample count. Default 2000. */
-  resamples?: number;
-  /** Statistic to bootstrap. Default 'median'. */
-  statistic?: 'median' | 'mean';
-  /** Deterministic seed. If omitted, derived from the deltas so the interval
-   *  is reproducible regardless. */
-  seed?: number;
-}
-/**
- * Paired bootstrap on (after − before) deltas. Returns a CI on the chosen
- * statistic (median by default); pairs are resampled with replacement. Throws
- * on unequal sample sizes.
- *
- * `low > threshold` carries the stated confidence ONLY at `n ≥
- * {@link BOOTSTRAP_GATE_MIN_N}`, which `gateEligible` reports. Below it the
- * check fires under a true null several times more often than nominal, so the
- * interval is descriptive spread and a promotion must not turn on it.
- */
-declare function pairedBootstrap(before: number[], after: number[], opts?: PairedBootstrapOptions): PairedBootstrapResult;
-/** Pre-registered direction for a one-sided paired sign test. */
-type SignTestAlternative = 'greater' | 'less';
-/** Exact one-sided sign-test result for paired numeric differences. */
-interface PairedSignTestResult {
-  /** Total supplied differences, including zero ties. */
-  n: number;
-  /** Strictly positive differences. */
-  positive: number;
-  /** Strictly negative differences. */
-  negative: number;
-  /** Zero differences excluded from the binomial test. */
-  ties: number;
-  /** Non-zero differences used by the binomial test. */
-  nNonTies: number;
-  /** Direction of the pre-registered alternative hypothesis. */
-  alternative: SignTestAlternative;
-  /** Exact one-sided p-value under P(positive) = P(negative) = 0.5. */
-  pValue: number;
-}
-/**
- * Exact one-sided sign test over paired differences.
- *
- * Pass `after[i] - before[i]` for each matched item. `alternative = 'greater'`
- * tests whether positive signs are more likely than negative signs and returns
- * `P(Binomial(nNonTies, 0.5) >= positive)`. `alternative = 'less'` treats
- * negative signs as successes instead. With a continuous difference
- * distribution this is the usual directional median test. Exact zero
- * differences are ties and do not enter the binomial denominator. All-tie and
- * empty inputs return p = 1. Every input difference must be finite, and the
- * direction must be chosen explicitly so a caller cannot select it after
- * seeing the signs.
- */
-declare function pairedSignTest(differences: readonly number[], alternative: SignTestAlternative): PairedSignTestResult;
+import { E as PairedBootstrapResult } from "./index-DNXFzSpc.js";
 /** Which paired estimator produced the deciding interval. */
 type PairedDecisionStatistic = 'paired_risk_difference' | 'mean_bootstrap' | 'median_bootstrap';
 /** Which test carried the decision, given the estimator and the sample size. */
@@ -229,5 +119,5 @@ interface PairedDecisionShape {
  * position. Throws on unequal lengths.
  */
 declare function decidePairedPromotion(before: number[], after: number[], options?: PairedPromotionDecisionOptions): PairedPromotionDecision;
-export { PairedPromotionDecision as a, BOOTSTRAP_GATE_MIN_N as c, PairedSignTestResult as d, PairedTTestResult as f, pairedTTest as g, pairedSignTest as h, PairedMcNemarEvidence as i, PairedBootstrapOptions as l, pairedBootstrap as m, PairedDecisionShape as n, PairedPromotionDecisionOptions as o, SignTestAlternative as p, PairedDecisionStatistic as r, decidePairedPromotion as s, PairedDecisionMethod as t, PairedBootstrapResult as u };
-//# sourceMappingURL=paired-promotion-decision-BDnqepZ1.d.ts.map
+export { PairedPromotionDecision as a, PairedMcNemarEvidence as i, PairedDecisionShape as n, PairedPromotionDecisionOptions as o, PairedDecisionStatistic as r, decidePairedPromotion as s, PairedDecisionMethod as t };
+//# sourceMappingURL=paired-promotion-decision-DJU3fZxH.d.ts.map

package/dist/paired-promotion-decision-DJU3fZxH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paired-promotion-decision-DJU3fZxH.d.ts","names":[],"sources":["../src/paired-promotion-decision.ts"],"mappings":";;KA2DY;;KAMA;;UAGK;;EAEf;;EAEA;;EAEA;;EAEA;;UAGe;;;EAGf;;EAEA;;EAEA;;EAEA;;;;EAIA;;;;;;;;EAQA;;;;;EAKA;;;;;;;;;;;;EAYA;;UAGe;;EAEf;;EAEA;EACA;EACA,WAAW;EACX,QAAQ;;;;;EAKR;;EAEA;;EAEA;;EAEA;;EAEA;;;;EAIA,WAAW;;EAEX,SAAS;;;EAGT;;EAEA;;EAEA;;;EAGA;;EAEA;;EAEA;;;EAGA;;EAEA;;EAEA;;EAEA;;;UAIe;EACf,WAAW;;EAEX;;EAEA;;;;;;;iBA2Dc,sBACd,kBACA,iBACA,UAAS,iCACR"}

package/dist/{pareto-a3EOmjfe.js → pareto-fJZg8pXm.js}

@@ -1,10 +1,7 @@
 import { a as hashCanonical, i as compareCodeUnits, r as canonicalString } from "./canonical-CicJlINA.js";
-import { t as mean } from "./mean-D1d6gedE.js";
+import { Q as confidenceInterval, ct as mean, f as DECISION_PAIRED_DELTA_STATISTIC, w as wilson } from "./statistics-CvvC-MPv.js";
 import { t as mulberry32 } from "./random-DrzcgC7F.js";
-import { t as confidenceInterval } from "./descriptive-B3Eb7tX0.js";
-import { s as wilson } from "./paired-binary-CMzmSSd5.js";
-import { n as DECISION_PAIRED_DELTA_STATISTIC } from "./paired-tests-Buh6feJ4.js";
-import { i as pairedDeltaTest, r as minimumPairsForPairedDeltaTest, t as decidePairedPromotion } from "./paired-promotion-decision-CiueaTTj.js";
+import { i as pairedDeltaTest, r as minimumPairsForPairedDeltaTest, t as decidePairedPromotion } from "./paired-promotion-decision-Bi9__RQS.js";
 import { a as SearchLedgerError } from "./search-ledger-file-BhOdgYIt.js";
 import { c as redactText } from "./redact-zp_ILC4l.js";
 import { l as searchUnitScores, p as USD_TOLERANCE, t as FileSearchLedger, u as searchCellId } from "./search-ledger-Dk-yk5Li.js";
@@ -2609,4 +2606,4 @@ function paretoFrontierWithCrowding(candidates, objectives) {
 }
 export { normalizeSignedZero as A, SEARCH_ESTIMATOR as C, searchEstimateMethod as D, searchCellSetDigest as E, searchPosterior as O, requiredPairsForPairedPromotion as S, estimateNodeFromCells as T, planSearchClaim as _, searchDivergence as a, verifySearchClaim as b, MIN_OUTCOMES_FOR_WEIGHT as c, rankingSplit as d, summarizeSamples as f, decideSearchClaim as g, SEARCH_CLAIM_RULE as h, runSearch as i, seedFromDigest as k, operatorYield as l, searchExpansionIndex as m, paretoFrontier as n, searchPolicyView as o, SEARCH_KERNEL_SOURCE as p, paretoFrontierWithCrowding as r, EXPANSION_OPERATORS as s, dominates as t, INSUFFICIENT_FROM as u, searchClaimDecision as v, estimateNode as w, pairedPromotionPower as x, searchClaimReserveUsd as y };
 
-//# sourceMappingURL=pareto-a3EOmjfe.js.map
+//# sourceMappingURL=pareto-fJZg8pXm.js.map