@tangle-network/agent-eval 0.144.6 → 0.144.8

package/dist/experiment/index.d.ts

@@ -0,0 +1,802 @@
+import { l as ValidationError, r as CaptureIntegrityError } from "../errors-CKPfb2aH.js";
+import { B as eProcess, J as mcnemarRequiredN, K as mcnemar, N as benjaminiHochberg, P as bonferroni, Q as pairedBootstrap, S as ProportionInterval, V as holm, Y as mulberry32, _t as wilson, d as EProcessState, dt as requiredPairedSampleSize, f as EProcessStep, ft as requiredSampleSize, it as pairedRiskDifferenceScore, l as EProcess, nt as pairedRiskDifference, q as mcnemarPower, rt as pairedRiskDifferenceExact, t as BOOTSTRAP_GATE_MIN_N, tt as pairedMde, u as EProcessOptions, v as PairedBootstrapOptions, y as PairedBootstrapResult } from "../statistics-D6Uebe_4.js";
+import { A as PairArmsResult, C as hashJson, D as MatchedPair, I as comparePairedArms, L as pairArms, M as PairedArmRow, R as pairRunRecords, S as evaluateHypothesis, T as verifyManifest, _ as HypothesisManifest, c as pairHoldout, d as SequentialDecision, f as SequentialObservation, g as sequentialPairedGate, h as sequentialDecide, i as PairedHoldout, k as PairArmsOptions, m as SequentialPairedGateOptions, n as HeldoutSignificance, p as SequentialPairedGate, r as HeldoutSignificanceOptions, s as heldoutSignificance, v as HypothesisResult, w as signManifest, x as canonicalize, y as SignedManifest } from "../statistical-heldout-Dn9ruizm.js";
+import { S as powerPreflight, b as PowerPreflight, c as PromotionPolicy, d as paretoSignificanceGate, i as EvidenceVector, l as buildEvidenceVector, u as paretoPolicy, x as PowerPreflightOptions } from "../promotion-policy-ChWhTDBH.js";
+import { C as ClusteredPairedBinaryOptions, E as clusteredPairedBinary, S as ClusteredMatchedPair, T as ClusteredPairedBinaryStatistics, _ as inMemoryExperimentStore, a as ExperimentStats, b as ClusterSignFlipResult, i as ExperimentRep, l as ExperimentVerdict, m as fileExperimentStore, n as Experiment, s as ExperimentTracker, v as ClusterBootstrapInterval, w as ClusteredPairedBinaryResult, x as ClusteredBinaryCluster } from "../experiment-tracker-IMntXr6J.js";
+import { a as PairedEvalueStep, c as pairedEvalueSequence, i as PairedEvalueSequence, r as PairedEvalueOptions } from "../sequential-CYwq6Ff_.js";
+//#region src/experiment/ast.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>;
+/** A decision rule's branches did not cover the evidence. */
+declare class DecisionTableNotTotalError extends ValidationError {}
+/**
+ * Closed-key comparison over a declared record schema. The only leaf node.
+ * `field` is a dot-separated path into an evidence record.
+ */
+type Predicate = {
+  kind: 'compare';
+  field: string;
+  op: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte';
+  value: JsonValue;
+} | {
+  kind: 'in';
+  field: string;
+  values: JsonValue[];
+} | {
+  kind: 'all';
+  of: Predicate[];
+} | {
+  kind: 'any';
+  of: Predicate[];
+} | {
+  kind: 'not';
+  of: Predicate;
+};
+/** Read a dot-separated field path. Missing segments yield `undefined`. */
+declare function readField(record: EvidenceRecord, path: string): unknown;
+/** Evaluate a predicate against one evidence record. */
+declare function evaluatePredicate(predicate: Predicate, record: EvidenceRecord): boolean;
+/**
+ * One monotone funnel stage. `waives` names substrate admission conditions
+ * deliberately NOT applied, so a waiver is registered, never implicit.
+ */
+interface AdmissionStage {
+  id: string;
+  keep: Predicate;
+  waives?: string[];
+}
+/** A partition is a set reported separately and never pooled. */
+interface AdmissionPartition {
+  id: string;
+  /** Stage whose dropped rows this partition draws from. */
+  from: string;
+  keep: Predicate;
+  pooling: 'never';
+}
+/** Declarative row-admission funnel. Stages only remove rows. */
+interface AdmissionRule {
+  population: string;
+  stages: AdmissionStage[];
+  partitions?: AdmissionPartition[];
+}
+/**
+ * Deterministic subset selection. `reads` is the closed field set the rule
+ * may touch — outcome-contaminated selection is unrepresentable because an
+ * outcome field is simply not in the list.
+ */
+type SelectionRule = {
+  kind: 'round-robin';
+  groupBy: string;
+  groupOrder: 'lex-asc';
+  withinOrder: {
+    field: string;
+    dir: 'asc' | 'desc';
+  };
+  take: number;
+  reads: string[];
+} | {
+  kind: 'filter-of';
+  /** Name of the sealed subset or selection this rule filters. */
+  base: string;
+  keep: Predicate;
+  order: {
+    field: string;
+    dir: 'asc' | 'desc';
+  };
+};
+/**
+ * Execute a selection rule.
+ *
+ * Round-robin walks groups in lexicographic order and takes ids in
+ * within-group order until `take` ids are chosen. Filter-of keeps the ids of
+ * `bases[rule.base]` whose record satisfies the predicate, in the registered
+ * order. Ids absent from `records` are evaluated on their id alone (fields
+ * derived from the id via `idFields`), so a sealed base outlives its source
+ * records.
+ */
+declare function runSelectionRule(rule: SelectionRule, records: readonly EvidenceRecord[], options: {
+  /** Field carrying a row's identity. */
+  idField: string;
+  /** Sealed or previously-computed subsets, by name. */
+  bases?: Record<string, readonly string[]>;
+  /** Derive predicate-readable fields from a bare id when its record is absent. */
+  idFields?: (id: string) => EvidenceRecord;
+}): string[];
+/** A named set of row identities, built from arm rows and an event predicate. */
+type SetExpr = {
+  kind: 'rows-where';
+  arm: string;
+  event: Predicate;
+} | {
+  kind: 'intersect';
+  of: SetExpr[];
+};
+/**
+ * What the experiment measures. Every estimand names the fields it reads, so
+ * the sealed tree records the full data dependency of the number.
+ */
+type Estimand = {
+  kind: 'rate';
+  event: Predicate;
+  over: 'rollouts';
+} | {
+  kind: 'rate-at-least-once';
+  event: Predicate;
+  groupBy: string;
+} | {
+  kind: 'paired-mean-diff';
+  armField: string;
+  treatment: string;
+  control: string;
+  pairBy: string;
+  value: string;
+  /** A pair one arm did not answer contributes a difference of exactly zero. */
+  missing: 'zero-diff';
+} | {
+  kind: 'set-ratio';
+  armField: string;
+  idField: string;
+  numerator: SetExpr;
+  denominator: SetExpr;
+};
+interface EstimandResult {
+  value: number;
+  numerator: number;
+  denominator: number;
+}
+/** Compute an estimand over evidence rows. Pure; reads only registered fields. */
+declare function computeEstimand(estimand: Estimand, rows: readonly EvidenceRecord[]): EstimandResult;
+/** How uncertainty is computed. The seed is part of the registration. */
+type IntervalSpec = {
+  kind: 'cluster-bootstrap';
+  clusterBy: 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 the per-row `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[];
+  value: string;
+} | {
+  kind: 'binomial';
+  successes: number;
+  trials: number;
+}): ComputedInterval;
+/** Decision guards read only named derived quantities — never raw rows. */
+type Condition = {
+  kind: 'interval-excludes-zero';
+  interval: string;
+  sign: 'positive' | 'negative';
+} | {
+  kind: 'interval-includes-zero';
+  interval: string;
+} | {
+  kind: 'quantity-threshold';
+  quantity: string;
+  op: 'gte' | 'lte' | 'gt' | 'lt';
+  value: number;
+} | {
+  kind: 'obligation-met';
+  obligation: string;
+} | {
+  kind: 'all';
+  of: Condition[];
+} | {
+  kind: 'any';
+  of: Condition[];
+} | {
+  kind: 'not';
+  of: Condition;
+};
+/** The named quantities a decision rule may read. Nothing else reaches it. */
+interface DerivedQuantities {
+  intervals: Record<string, {
+    lower: number;
+    upper: number;
+  }>;
+  quantities: Record<string, number>;
+  obligationsMet: Record<string, boolean>;
+}
+declare function evaluateCondition(condition: Condition, evidence: DerivedQuantities): boolean;
+interface DecisionBranch {
+  when: Condition;
+  verdict: string;
+  report: string[];
+}
+/**
+ * Ordered decision table: the first branch whose condition holds fires, and a
+ * table no branch matches throws — a non-total registration is a defect, not
+ * an implicit verdict. `report-only` registers the ABSENCE of a verdict
+ * branch: the estimate and the per-row table are the finding, and the
+ * registered meaning prose rides as non-executable interpretation data.
+ */
+type DecisionRule = {
+  kind: 'table';
+  branches: DecisionBranch[];
+} | {
+  kind: 'report-only';
+  estimands: string[];
+  intervals: string[];
+  perRow: string[];
+  interpretation?: {
+    onQualitative: string;
+    consequence: string;
+  }[];
+};
+interface DecisionOutcome {
+  verdict: string;
+  report: string[];
+}
+declare function executeDecisionRule(rule: DecisionRule, evidence: DerivedQuantities): DecisionOutcome;
+/** A registered control that must exist before a class of verdicts is read. */
+interface Obligation {
+  id: string;
+  appliesToVerdicts: string[];
+  control: string;
+}
+/** Pre-spend design checks. Each returns pass/fail plus its evidence. */
+type ValidityGate = {
+  kind: 'oracle-determinism';
+  unit: 'suite' | 'assertion';
+  replicates: number;
+  maxFlipRate: number;
+} | {
+  kind: 'population-reproducibility';
+  joinOn: string;
+  compare: string[];
+  maxChangedRows: number;
+} | {
+  kind: 'provenance-assertion';
+  claim: Predicate;
+} | {
+  kind: 'power-floor';
+  target: number;
+  effectGrid: number[];
+  sim: {
+    trials: number;
+    resamples: number;
+    seed: number;
+  };
+} | {
+  kind: 'identity';
+  field: 'served-model';
+  op: 'basename-eq';
+  onFail: 'abort';
+};
+interface GateResult {
+  id: string;
+  passed: boolean;
+  evidence: JsonValue;
+}
+/**
+ * Replicate-flip counting over graded states. A state whose replicates split
+ * between pass and fail is flipping; its flip rate is the minority share.
+ */
+declare function evaluateOracleDeterminismGate(id: string, gate: Extract<ValidityGate, {
+  kind: 'oracle-determinism';
+}>, repsByState: Record<string, readonly boolean[]>): GateResult;
+/**
+ * Join two population snapshots on `joinOn` and compare the registered fields.
+ * Only rows present in both snapshots are compared; a presence change is a
+ * different failure and needs its own gate.
+ */
+declare function evaluatePopulationReproducibilityGate(id: string, gate: Extract<ValidityGate, {
+  kind: 'population-reproducibility';
+}>, populations: {
+  left: readonly EvidenceRecord[];
+  right: readonly EvidenceRecord[];
+}): GateResult;
+/** The registered claim about provenance must hold on the provenance record. */
+declare function evaluateProvenanceGate(id: string, gate: Extract<ValidityGate, {
+  kind: 'provenance-assertion';
+}>, provenance: EvidenceRecord): GateResult;
+/** Final path segment equality between the pinned and the served identity. */
+declare function evaluateIdentityGate(id: string, _gate: Extract<ValidityGate, {
+  kind: 'identity';
+}>, identities: {
+  pinned: string;
+  served: string;
+}): GateResult;
+/**
+ * The design's power curve must reach the registered target at some grid
+ * effect. The curve must cover the registered effect grid exactly — a curve
+ * computed on a different grid is different evidence and is refused.
+ */
+declare function evaluatePowerFloorGate(id: string, gate: Extract<ValidityGate, {
+  kind: 'power-floor';
+}>, curve: readonly {
+  effect: number;
+  power: number;
+}[]): GateResult;
+/** Checks as prerequisites: any named gate failing refuses the spend. */
+interface HaltRule {
+  when: {
+    kind: 'any-gate-failed';
+    gates: string[];
+  };
+  action: 'refuse-spend';
+  report: 'settling-n';
+}
+interface HaltOutcome {
+  fired: boolean;
+  action: 'refuse-spend' | null;
+  failedGates: string[];
+}
+declare function evaluateHaltRule(halt: HaltRule, gates: readonly GateResult[]): HaltOutcome;
+/**
+ * Spend schedules as data. `ledger` names every entry the ceiling counts, so
+ * what the gate reads is registered, not improvised at gate time.
+ */
+type BudgetRule = {
+  kind: 'uniform-pass';
+  ceilingUsd: number;
+  maxPasses: number;
+  projection: 'last-pass-cost';
+  costSource: 'priced-per-call';
+  ledger: {
+    id: string;
+    usd: number;
+  }[];
+  partialPass: 'report-never-lift';
+} | {
+  kind: 'n-ladder';
+  steps: number[];
+  ceilingUsd: number;
+  projection: 'unit-cost-times-rows-times-n';
+  onExhaust: 'refuse-report-projection';
+};
+interface UniformPassDecision {
+  pass: number;
+  cumulativeBefore: number;
+  projected: number;
+  go: boolean;
+}
+interface UniformPassSchedule {
+  decisions: UniformPassDecision[];
+  uniformN: number;
+}
+/**
+ * Execute the uniform-pass schedule against measured pass costs. Pass 1 always
+ * runs; each later pass runs only when the cumulative spend plus the last
+ * measured pass cost stays at or under the registered ceiling. The registered
+ * ledger is the pre-spend the ceiling counts.
+ */
+declare function runUniformPassBudget(rule: Extract<BudgetRule, {
+  kind: 'uniform-pass';
+}>, measuredPassCosts: readonly number[]): UniformPassSchedule;
+interface NLadderProjection {
+  chosenN: number | null;
+  projections: {
+    n: number;
+    projectedUsd: number;
+    affordable: boolean;
+  }[];
+  refusal: null | {
+    onExhaust: 'refuse-report-projection';
+    reason: string;
+  };
+}
+/**
+ * Walk the registered n-ladder and pick the first affordable step. When no
+ * step fits the ceiling, the rule refuses and reports the projection instead
+ * of shrinking the row set — "never subset rows" is the registered invariant.
+ */
+declare function projectNLadderBudget(rule: Extract<BudgetRule, {
+  kind: 'n-ladder';
+}>, measured: {
+  unitCostUsd: number;
+  rows: number;
+}): NLadderProjection;
+/** Arm budget matching as a refusal, not prose. Verified by `verifyMatchedBudgets`. */
+interface MatchedBudgetRule {
+  measure: 'realized-tokens';
+  tolerance: number;
+  onFail: 'refuse-contrast';
+}
+/** Carrier faults are reissued; model outcomes stand. Closed enumeration. */
+interface ReissuePolicy {
+  carrierEvents: ('http-status' | 'transport-error' | 'deadline' | 'empty-content')[];
+  modelOutcomesStand: true;
+  maxIssues: number;
+}
+type ReissueVerdict = 'reissue' | 'stands' | 'exhausted';
+/**
+ * Classify one rollout event under the registered reissue policy. A carrier
+ * event within the issue budget is reissued; a model outcome always stands;
+ * a carrier event past `maxIssues` is exhausted and reported, never retried.
+ */
+declare function classifyReissue(policy: ReissuePolicy, event: string, issuesSoFar: number): ReissueVerdict;
+//#endregion
+//#region src/experiment/budget.d.ts
+/** Arms whose realized budgets diverge past the registered tolerance. */
+declare class MatchedBudgetError extends CaptureIntegrityError {}
+interface ArmRealizedBudget {
+  armId: string;
+  /** Realized prompt + completion tokens the arm actually consumed. */
+  realizedTokens: number;
+}
+interface MatchedBudgetVerdict {
+  rule: MatchedBudgetRule;
+  arms: ArmRealizedBudget[];
+  /** (max - min) / max over all arms; 0 when every arm spent nothing. */
+  maxRelativeGap: number;
+  /** The two arms with the widest gap; null when fewer than two arms. */
+  widestPair: [string, string] | null;
+  matched: boolean;
+  /** Populated exactly when `matched` is false. */
+  refusal: null | {
+    onFail: 'refuse-contrast';
+    reason: string;
+  };
+}
+/**
+ * Compare realized per-arm spend under the registered tolerance. Requires at
+ * least two arms — a single arm has nothing to match against. Negative or
+ * non-finite token counts are refused as evidence corruption, not compared.
+ */
+declare function verifyMatchedBudgets(rule: MatchedBudgetRule, arms: readonly ArmRealizedBudget[]): MatchedBudgetVerdict;
+/** Throw the refusal for callers that gate the contrast on it. */
+declare function assertMatchedBudgets(rule: MatchedBudgetRule, arms: readonly ArmRealizedBudget[]): MatchedBudgetVerdict;
+//#endregion
+//#region src/experiment/funnel.d.ts
+/** A funnel stage gained rows, double-counted them, or failed to reconcile. */
+declare class FunnelIntegrityError extends CaptureIntegrityError {}
+interface FunnelStageCount {
+  id: string;
+  entering: number;
+  excluded: number;
+  remaining: number;
+  /** Named exclusion reasons summing to `excluded`, when the stage has them. */
+  exclusions?: Record<string, number>;
+  /** Substrate checks this stage deliberately does not apply. Registered, never implicit. */
+  waives?: string[];
+}
+interface FunnelPartitionCount {
+  id: string;
+  /** Stage whose excluded rows the partition draws from. */
+  from: string;
+  count: number;
+  /** A partition is reported separately and never pooled into the survivors. */
+  pooling: 'never';
+}
+interface ExperimentFunnel {
+  population: string;
+  input: number;
+  stages: FunnelStageCount[];
+  surviving: number;
+  partitions: FunnelPartitionCount[];
+}
+interface FunnelStageInput {
+  id: string;
+  /** Rows this stage removed. */
+  excluded: number;
+  exclusions?: Record<string, number>;
+  waives?: string[];
+}
+/**
+ * Build a funnel from counts and refuse anything non-monotone.
+ *
+ * Refusals: a negative count, a stage that gains rows (excluded < 0 is the
+ * only way to gain — `remaining = entering - excluded` by construction, so a
+ * gain cannot be smuggled in through `remaining`), named exclusions that do
+ * not sum to the stage total, and a partition drawing from an unknown stage
+ * or exceeding what that stage excluded.
+ */
+declare function buildFunnel(input: {
+  population: string;
+  input: number;
+  stages: FunnelStageInput[];
+  partitions?: {
+    id: string;
+    from: string;
+    count: number;
+  }[];
+}): ExperimentFunnel;
+/** A chain that does not add up is a broken denominator, so this throws. */
+declare function assertFunnelReconciles(funnel: ExperimentFunnel): void;
+interface AdmissionExecution {
+  funnel: ExperimentFunnel;
+  survivors: EvidenceRecord[];
+  /** Partition rows by partition id, reported separately and never pooled. */
+  partitionRows: Record<string, EvidenceRecord[]>;
+}
+/**
+ * Run a sealed admission rule over evidence records. Each stage keeps the rows
+ * its predicate accepts; partitions draw from the rows their source stage
+ * dropped. The result embeds the funnel, so the denominator chain and the
+ * surviving rows can never disagree.
+ */
+declare function executeAdmissionRule(rule: AdmissionRule, records: readonly EvidenceRecord[]): AdmissionExecution;
+/**
+ * Chain two funnels whose boundary agrees: the second funnel's input must be
+ * exactly the first funnel's survivors. Anything else is a gap or an
+ * injection, and both are refused.
+ */
+declare function composeFunnels(first: ExperimentFunnel, second: ExperimentFunnel): ExperimentFunnel;
+/**
+ * Text render of the chain. One row per stage; the reconciliation line at the
+ * bottom restates `input = surviving + excluded` so a reader can check the
+ * arithmetic without a tool.
+ */
+declare function renderFunnelTable(funnel: ExperimentFunnel): string;
+//#endregion
+//#region src/experiment/define.d.ts
+/** A sealed experiment whose digest no longer matches its spec. */
+declare class SealIntegrityError extends ValidationError {}
+interface ArmSpec {
+  id: string;
+  role: 'treatment' | 'control';
+  /** Digest of the AgentProfile the arm runs under. */
+  profileDigest?: string;
+  /** Digest of the pinned execution policy the arm runs under. */
+  policyDigest?: string;
+  /** Registered arm pins (model, seed, step budget, ...) as data. */
+  pins?: Record<string, JsonValue>;
+}
+type OutcomeSpec = {
+  kind: 'binary';
+  /** Where the pass verdict comes from, e.g. 'injected-suite'. */
+  source?: string;
+  digestVerified?: boolean;
+  /** What counts as a pass, e.g. 'exit-0' or 'reward-file-contains-1'. */
+  pass?: string;
+  /** Errored rollouts stay in the denominator; dropping them is unregistered. */
+  droppedRollouts?: 'forbidden';
+} | {
+  kind: 'bounded-score';
+  min: number;
+  max: number;
+  orientation: 'higher-is-better' | 'lower-is-better';
+};
+/**
+ * Per-rollout seed derivation as a closed source list. `arm` is not in the
+ * union, so arm-dependent seeding is unrepresentable.
+ */
+interface SeedDerivation {
+  from: ('seed' | 'rowId' | 'rolloutIndex')[];
+}
+interface ExperimentSpec {
+  id: string;
+  /** Human prose for the audit trail — never executable. */
+  hypothesis?: string;
+  arms: ArmSpec[];
+  outcome: OutcomeSpec;
+  admission?: AdmissionRule;
+  /** Named deterministic subset rules. */
+  selections?: Record<string, SelectionRule>;
+  /**
+   * Selection OUTPUTS pinned into the seal. A filter-of base resolves here, so
+   * reusing an earlier draw is registered and a re-draw is a new digest.
+   */
+  sealedSubsets?: Record<string, string[]>;
+  estimands?: Record<string, Estimand>;
+  intervals?: Record<string, IntervalSpec>;
+  decision: DecisionRule;
+  obligations?: Obligation[];
+  /** Named pre-spend validity gates; the halt rule references these names. */
+  gates?: Record<string, ValidityGate>;
+  halt?: HaltRule;
+  budget?: BudgetRule;
+  matchedBudget?: MatchedBudgetRule;
+  reissue?: ReissuePolicy;
+  seedDerivation?: SeedDerivation;
+  seed?: number;
+}
+/**
+ * Validate every cross-reference inside a spec and freeze it.
+ *
+ * A decision condition may only read a registered interval, a registered
+ * estimand, or a registered obligation; a halt rule may only reference
+ * registered gates; a filter-of base must resolve to a registered selection
+ * or sealed subset. Anything else is refused here, before sealing.
+ */
+declare function defineExperiment(spec: ExperimentSpec): ExperimentSpec;
+interface SealAmendment {
+  /** ISO8601 timestamp of the re-seal. */
+  at: string;
+  reason: string;
+  /** Blindness attestations: what was verifiably unseen when the amendment was made. */
+  blind: string[];
+  /** Digest of the spec after this amendment. */
+  digest: string;
+}
+interface SealedExperiment {
+  spec: ExperimentSpec;
+  /** sha256-content over the canonicalized spec — the current registration. */
+  digest: string;
+  algo: 'sha256-content';
+  sealedAt: string;
+  /** Digest of the original registration, before any amendment. */
+  initialDigest: string;
+  amendments: SealAmendment[];
+}
+/** Validate, canonicalize, and hash a spec into its registration. */
+declare function sealExperiment(spec: ExperimentSpec, options?: {
+  sealedAt?: string;
+}): Promise<SealedExperiment>;
+/**
+ * Amend a sealed experiment. The current seal is verified first, the new spec
+ * is validated and re-hashed, and the amendment appends to the digest chain.
+ * There is no way to change what is decided without producing a new digest.
+ */
+declare function amendExperiment(sealed: SealedExperiment, amendment: {
+  spec: ExperimentSpec;
+  reason: string;
+  blind: string[];
+  at?: string;
+}): Promise<SealedExperiment>;
+/** True when the sealed digest still matches the spec it carries. */
+declare function verifySealedExperiment(sealed: SealedExperiment): Promise<boolean>;
+/** Evidence a gate executor consumes, discriminated to match the gate kind. */
+type GateEvidence = {
+  kind: 'oracle-determinism';
+  repsByState: Record<string, readonly boolean[]>;
+} | {
+  kind: 'population-reproducibility';
+  left: readonly EvidenceRecord[];
+  right: readonly EvidenceRecord[];
+} | {
+  kind: 'provenance-assertion';
+  provenance: EvidenceRecord;
+} | {
+  kind: 'identity';
+  pinned: string;
+  served: string;
+} | {
+  kind: 'power-floor';
+  curve: readonly {
+    effect: number;
+    power: number;
+  }[];
+};
+/**
+ * Executors bound to one verified seal. Every method reads its rule from the
+ * sealed spec; evidence is the only argument anywhere.
+ */
+interface RegisteredExperiment {
+  readonly sealed: SealedExperiment;
+  /** Execute the registered decision rule on derived quantities. */
+  decide(evidence: DerivedQuantities): DecisionOutcome;
+  /** Run the registered admission funnel over evidence rows. */
+  admit(records: readonly EvidenceRecord[]): AdmissionExecution;
+  /** Run a registered selection rule. Filter-of bases resolve to sealed subsets. */
+  select(name: string, records: readonly EvidenceRecord[], options: {
+    idField: string;
+  }): string[];
+  /** Evaluate a registered validity gate on evidence of the matching kind. */
+  gate(name: string, evidence: GateEvidence): GateResult;
+  /** Evaluate the registered halt rule over gate results. */
+  halt(gates: readonly GateResult[]): HaltOutcome;
+  /** Execute the registered uniform-pass budget schedule. */
+  runUniformPassBudget(measuredPassCosts: readonly number[]): UniformPassSchedule;
+  /** Project the registered n-ladder budget. */
+  projectNLadderBudget(measured: {
+    unitCostUsd: number;
+    rows: number;
+  }): NLadderProjection;
+  /** Verify realized arm budgets under the registered matched-budget rule. */
+  matchedBudgets(arms: readonly ArmRealizedBudget[]): MatchedBudgetVerdict;
+  /** Compute a registered estimand over evidence rows. */
+  estimate(name: string, rows: readonly EvidenceRecord[]): EstimandResult;
+  /** Compute a registered interval spec. */
+  interval(name: string, evidence: {
+    kind: 'rows';
+    rows: readonly EvidenceRecord[];
+    value: string;
+  } | {
+    kind: 'binomial';
+    successes: number;
+    trials: number;
+  }): ComputedInterval;
+}
+/**
+ * Verify the seal and return executors bound to it. This is the module's only
+ * execution surface: a rule that is not in the sealed spec cannot run, and a
+ * rule that is cannot run differently.
+ */
+declare function openSealedExperiment(sealed: SealedExperiment): Promise<RegisteredExperiment>;
+//#endregion
+//#region src/experiment/power.d.ts
+/** A design refused at configuration time, before any spend. */
+declare class DesignRefusalError extends ValidationError {}
+interface ClusteredPowerOptions {
+  /** Rows per independent cluster, e.g. [6, 3, 3, 2]. */
+  clusterSizes: number[];
+  /** Per-row effect grid: each effect is P(win) - P(loss) added to the base rates. */
+  effects: number[];
+  /** Deterministic seed for outcome draws and bootstrap resampling. */
+  seed: number;
+  /** Simulated experiments per effect. Default 2000. */
+  trials?: number;
+  /** Whole-cluster bootstrap draws per trial. Default 4000. */
+  resamples?: number;
+  /** Percentile interval level. Default 0.95. */
+  confidence?: number;
+  /** Sign-flip alpha the closed-form floor is checked against. Default 0.05. */
+  alpha?: number;
+  /** Power the design must reach at some grid effect. Default 0.8. */
+  targetPower?: number;
+  /** Base P(row favors treatment) with no effect. Default 0.10 (tie-heavy rows). */
+  baseWinRate?: number;
+  /** Base P(row favors control). Default 0.10. */
+  baseLossRate?: number;
+  /**
+   * Clusters whose rows carry outcome noise instead of signal: each row wins
+   * with `flipRate` and loses with `flipRate`, independent of the effect.
+   * Index into `clusterSizes`.
+   */
+  noisyClusters?: {
+    index: number;
+    flipRate: number;
+  }[];
+}
+interface ClusteredPowerPoint {
+  effect: number;
+  power: number;
+  medianCiWidth: number;
+}
+interface SignFlipFloor {
+  /** Smallest achievable two-sided p: 2^(1-C) for C clusters. */
+  twoSidedP: number;
+  /** Smallest achievable one-sided p: 2^-C. */
+  oneSidedP: number;
+  alpha: number;
+  /** False when the cluster count can never certify at `alpha`, at any effect. */
+  certifiableAtAlpha: boolean;
+  /** Smallest cluster count whose two-sided floor is at or under `alpha`. */
+  minClustersForAlpha: number;
+}
+interface ClusteredPowerRefusal {
+  verdict: 'underpowered';
+  reasons: string[];
+  recommendation: string;
+}
+interface ClusteredPowerResult {
+  clusterCount: number;
+  totalRows: number;
+  trials: number;
+  resamples: number;
+  seed: number;
+  confidence: number;
+  targetPower: number;
+  curve: ClusteredPowerPoint[];
+  /** Maximum simulated power across the effect grid. */
+  maxPower: number;
+  signFlipFloor: SignFlipFloor;
+  /** True only when the sign-flip floor certifies AND simulation reaches target. */
+  adequate: boolean;
+  /** Populated exactly when `adequate` is false. The refusal lives in the artifact. */
+  refusal: ClusteredPowerRefusal | null;
+}
+/**
+ * Simulate the power of a whole-cluster percentile-bootstrap design and refuse
+ * a structure that cannot reach the target at any registered effect.
+ */
+declare function clusteredPower(options: ClusteredPowerOptions): ClusteredPowerResult;
+/** Throw the refusal for callers that want configuration-time failure. */
+declare function assertDesignAdequate(result: ClusteredPowerResult): void;
+//#endregion
+export { type AdmissionExecution, type AdmissionPartition, type AdmissionRule, type AdmissionStage, type ArmRealizedBudget, type ArmSpec, BOOTSTRAP_GATE_MIN_N, type BudgetRule, type ClusterBootstrapInterval, type ClusterSignFlipResult, type ClusteredBinaryCluster, type ClusteredMatchedPair, type ClusteredPairedBinaryOptions, type ClusteredPairedBinaryResult, type ClusteredPairedBinaryStatistics, type ClusteredPowerOptions, type ClusteredPowerPoint, type ClusteredPowerRefusal, type ClusteredPowerResult, type ComputedInterval, type Condition, type DecisionBranch, type DecisionOutcome, type DecisionRule, DecisionTableNotTotalError, type DerivedQuantities, DesignRefusalError, type EProcess, type EProcessOptions, type EProcessState, type EProcessStep, type Estimand, type EstimandResult, type EvidenceRecord, type EvidenceVector, type Experiment, type ExperimentFunnel, type ExperimentRep, type ExperimentSpec, type ExperimentStats, ExperimentTracker, type ExperimentVerdict, FunnelIntegrityError, type FunnelPartitionCount, type FunnelStageCount, type FunnelStageInput, type GateEvidence, type GateResult, type HaltOutcome, type HaltRule, type HeldoutSignificance, type HeldoutSignificanceOptions, type HypothesisManifest, type HypothesisResult, type IntervalSpec, type JsonValue, MatchedBudgetError, type MatchedBudgetRule, type MatchedBudgetVerdict, type MatchedPair, type NLadderProjection, type Obligation, type OutcomeSpec, type PairArmsOptions, type PairArmsResult, type PairedArmRow, type PairedBootstrapOptions, type PairedBootstrapResult, type PairedEvalueOptions, type PairedEvalueSequence, type PairedEvalueStep, type PairedHoldout, type PowerPreflight, type PowerPreflightOptions, type Predicate, type PromotionPolicy, type ProportionInterval, type RegisteredExperiment, type ReissuePolicy, type ReissueVerdict, type SealAmendment, SealIntegrityError, type SealedExperiment, type SeedDerivation, type SelectionRule, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SetExpr, type SignFlipFloor, type SignedManifest, type UniformPassDecision, type UniformPassSchedule, type ValidityGate, amendExperiment, assertDesignAdequate, assertFunnelReconciles, assertMatchedBudgets, benjaminiHochberg, bonferroni, buildEvidenceVector, buildFunnel, canonicalize, classifyReissue, clusteredPairedBinary, clusteredPower, comparePairedArms, composeFunnels, computeEstimand, computeInterval, defineExperiment, eProcess, evaluateCondition, evaluateHaltRule, evaluateHypothesis, evaluateIdentityGate, evaluateOracleDeterminismGate, evaluatePopulationReproducibilityGate, evaluatePowerFloorGate, evaluatePredicate, evaluateProvenanceGate, executeAdmissionRule, executeDecisionRule, fileExperimentStore, hashJson, heldoutSignificance, holm, inMemoryExperimentStore, mcnemar, mcnemarPower, mcnemarRequiredN, mulberry32, openSealedExperiment, pairArms, pairHoldout, pairRunRecords, pairedBootstrap, pairedEvalueSequence, pairedMde, pairedRiskDifference, pairedRiskDifferenceExact, pairedRiskDifferenceScore, paretoPolicy, paretoSignificanceGate, powerPreflight, projectNLadderBudget, readField, renderFunnelTable, requiredPairedSampleSize, requiredSampleSize, runSelectionRule, runUniformPassBudget, sealExperiment, sequentialDecide, sequentialPairedGate, signManifest, verifyManifest, verifyMatchedBudgets, verifySealedExperiment, wilson };
+//# sourceMappingURL=index.d.ts.map