@elaraai/e3-ui 1.0.12 → 1.0.13

package/dist/src/experiment/types.d.ts

@@ -3,49 +3,32 @@
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
 /**
- * The `Experiment` render contract — the **e3-ui-owned** boundary types the
- * component reads and the developer's bound functions return.
+ * The `Experiment` render contract.
  *
- * @remarks
- * These are *not* causal-library types: `e3-ui` never imports
- * `east-py-datascience`. They are the small contract a sign-flip experiment
- * surface needs — the causal quantities (`effect` / `ci` / the ALE vectors /
- * the refuter numbers) plus the two additions the surface requires (`naive`
- * for the raw-vs-adjusted comparison and `balance` for the confounder table).
+ * These types are **replicated verbatim (snake_case)** from
+ * `east-py-datascience`'s `Causal.Types.*`, so the engine's `Causal.experiment`
+ * result unifies **structurally** with the component's binding — replicate, don't
+ * share (East type equality is structural; `e3-ui` never imports
+ * `east-py-datascience`). Keep these byte-identical to the datascience
+ * definitions — they are kept in sync by hand.
  *
- * The split follows the **string-vs-variant rule** ({@link ExperimentSpecType}):
- *
- * - **Closed choices are variants** — the user's Advanced estimator / target /
- *   trim selections ({@link EstimatorType}, {@link TargetUnitsType},
- *   {@link TrimType}). They mirror the causal vocabulary *structurally*, so the
- *   developer's ~10-line `spec → CausalEffectConfig` bridge is an identity map
- *   on these fields — but the type lives here, owned by the surface.
- * - **Column references are strings** — `treatment` / `outcome` / `confounders`
- *   are field names introspected from the bound dataset's row struct (the
- *   `Table` pattern), so they are open over whatever columns the data has.
- * - **Presentation is derived, never stored** — no `tone` / bar width / label /
- *   sentence appears here. The renderer composes every word and colour from the
- *   numbers + the user's chosen column names.
- *
- * Where a shape overlaps the library (`Ci`, the ALE vectors) it is
- * **structurally identical**, so values unify by shape across the package
- * boundary with no shared package and no conversion.
- *
- * Reached via `Experiment.Types.*` (like `Table.Types.*`), not public named
- * exports — users only touch them to type the bound functions / seed datasets.
+ * The user edits an {@link ExperimentConfigType} (the staged "question + method")
+ * and **Apply** runs the one bound `experiment` function, which returns an
+ * {@link ExperimentResultType} — the naive vs adjusted effect, confounder
+ * balance, propensity overlap, a robustness summary, and an honesty
+ * {@link ExperimentVerdictType}. `adjusted` is `none` when the engine refuses.
  *
  * @packageDocumentation
  */
-import { StringType, FloatType, IntegerType, BooleanType, NullType, DateTimeType, ArrayType, StructType, VariantType, OptionType, DictType, VectorType } from '@elaraai/east';
-/**
- * Inverse-propensity weighting scheme for the
- * {@link EstimatorType | propensity-weighting} estimator. Structurally mirrors
- * the causal library's weighting-scheme variant.
- *
- * @property ips_weight - Raw inverse propensity weights.
- * @property ips_stabilized_weight - Stabilised weights (recommended; lower variance).
- * @property ips_normalized_weight - Normalised inverse propensity weights.
- */
+import { StructType, VariantType, OptionType, ArrayType, DictType, FloatType, IntegerType, BooleanType, StringType, NullType, DateTimeType, VectorType } from '@elaraai/east';
+/** A confidence interval. */
+export declare const CiType: StructType<{
+    readonly lower: FloatType;
+    readonly upper: FloatType;
+}>;
+/** Type alias for {@link CiType}. */
+export type CiType = typeof CiType;
+/** Inverse-propensity weighting scheme. */
 export declare const WeightingSchemeType: VariantType<{
     readonly ips_weight: NullType;
     readonly ips_stabilized_weight: NullType;
@@ -53,16 +36,7 @@ export declare const WeightingSchemeType: VariantType<{
 }>;
 /** Type alias for {@link WeightingSchemeType}. */
 export type WeightingSchemeType = typeof WeightingSchemeType;
-/**
- * How the like-for-like comparison is estimated — the user's "method" choice in
- * the Advanced panel. Closed set, so a variant; structurally mirrors the causal
- * estimator vocabulary.
- *
- * @property linear_regression - Regress the outcome on treatment + confounders.
- * @property propensity_score_weighting - Re-weight rows by treatment
- *   propensity (binary treatment); carries the optional
- *   {@link WeightingSchemeType}.
- */
+/** Backdoor-adjusted effect estimator. */
 export declare const EstimatorType: VariantType<{
     readonly linear_regression: NullType;
     readonly propensity_score_weighting: StructType<{
@@ -75,14 +49,7 @@ export declare const EstimatorType: VariantType<{
 }>;
 /** Type alias for {@link EstimatorType}. */
 export type EstimatorType = typeof EstimatorType;
-/**
- * Which population the effect is reported for — the user's "who" choice. Closed
- * set, so a variant; structurally mirrors the causal target-units vocabulary.
- *
- * @property ate - Everyone (average treatment effect).
- * @property att - The treated group (average effect on the treated).
- * @property atc - The untreated group (average effect on the controls).
- */
+/** Population the effect is reported for. */
 export declare const TargetUnitsType: VariantType<{
     readonly ate: NullType;
     readonly att: NullType;
@@ -90,102 +57,41 @@ export declare const TargetUnitsType: VariantType<{
 }>;
 /** Type alias for {@link TargetUnitsType}. */
 export type TargetUnitsType = typeof TargetUnitsType;
-/**
- * Whether un-matchable rows are dropped before estimating — the user's "trim"
- * choice. Closed set, so a variant; structurally mirrors the causal
- * propensity-trim vocabulary.
- *
- * @property overlap - Keep only the common-support overlap of the two groups.
- * @property bounds - Keep rows whose propensity is inside explicit `lower` /
- *   `upper` bounds.
- */
-export declare const TrimType: VariantType<{
-    readonly overlap: NullType;
-    readonly bounds: StructType<{
-        readonly lower: FloatType;
-        readonly upper: FloatType;
-    }>;
+/** Bootstrap confidence-interval configuration. */
+export declare const BootstrapConfigType: StructType<{
+    readonly reps: IntegerType;
+    readonly cluster_column: OptionType<StringType>;
+    readonly confidence_level: OptionType<FloatType>;
+}>;
+/** Type alias for {@link BootstrapConfigType}. */
+export type BootstrapConfigType = typeof BootstrapConfigType;
+/** Which robustness checks to run. */
+export declare const RefuteSpecType: StructType<{
+    /** Permuted-treatment negative control — a real effect should vanish. */
+    readonly placebo: BooleanType;
+    /** Inject an independent random common cause — the effect should hold. */
+    readonly random_common_cause: BooleanType;
+    /** Re-estimate on random subsamples — the effect should be stable. */
+    readonly data_subset: BooleanType;
+    /** Unobserved-confounder strengths to simulate → the sensitivity / tipping curve. */
+    readonly sensitivity: OptionType<ArrayType<FloatType>>;
 }>;
-/** Type alias for {@link TrimType}. */
-export type TrimType = typeof TrimType;
+/** Type alias for {@link RefuteSpecType}. */
+export type RefuteSpecType = typeof RefuteSpecType;
 /**
- * The experiment the user framed in the set-up rail — the staged value the
- * pickers write and **Run** feeds to the bound `estimate` function.
+ * The experiment the user framed — the staged value the pickers write and
+ * **Apply** feeds to the bound `experiment` function.
  *
- * @remarks
- * `treatment` / `outcome` / `confounders` / `categorical` are **column names**
- * introspected from the bound dataset's row struct, so the surface re-frames
- * over whatever columns the data has (the `Table` pattern). The Advanced
- * choices ({@link EstimatorType}, {@link TargetUnitsType}, {@link TrimType}) are
- * variants. `population` is an optional Slice-style predicate set that narrows
- * the rows before estimating.
- *
- * @property treatment - The column whose change might cause the effect.
- * @property outcome - The column it might move.
- * @property confounders - The backdoor set — columns to adjust for.
- * @property categorical - Which of the confounders hold category codes (one-hot
- *   encoded by the estimator).
- * @property population - Optional row narrowing (AND-ed Slice predicates).
- * @property method - Optional estimator override (default: linear regression).
- * @property targetUnits - Optional population override (default: everyone).
- * @property trim - Optional un-matchable-row trimming (propensity weighting only).
+ * `treatment` / `outcome` / `common_causes` / `categorical` are **column names**
+ * introspected from the bound dataset's row struct (the `Table` pattern). The
+ * `method` / `estimand` advanced choices and the `min_*` guard thresholds are
+ * optional developer-defaulted, user-adjustable knobs.
  */
-export declare const ExperimentSpecType: StructType<{
+export declare const ExperimentConfigType: StructType<{
     readonly treatment: StringType;
     readonly outcome: StringType;
-    readonly confounders: ArrayType<StringType>;
-    readonly categorical: ArrayType<StringType>;
-    readonly population: OptionType<ArrayType<VariantType<{
-        readonly string: import("@elaraai/east").StructType<{
-            readonly fieldId: import("@elaraai/east").StringType;
-            readonly op: import("@elaraai/east").VariantType<{
-                readonly eq: import("@elaraai/east").StringType;
-                readonly neq: import("@elaraai/east").StringType;
-                readonly in: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                readonly notIn: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                readonly contains: import("@elaraai/east").StringType;
-                readonly matches: import("@elaraai/east").StringType;
-            }>;
-        }>;
-        readonly integer: import("@elaraai/east").StructType<{
-            readonly fieldId: import("@elaraai/east").StringType;
-            readonly op: import("@elaraai/east").VariantType<{
-                readonly eq: import("@elaraai/east").IntegerType;
-                readonly neq: import("@elaraai/east").IntegerType;
-                readonly lt: import("@elaraai/east").IntegerType;
-                readonly lte: import("@elaraai/east").IntegerType;
-                readonly gt: import("@elaraai/east").IntegerType;
-                readonly gte: import("@elaraai/east").IntegerType;
-                readonly in: import("@elaraai/east").SetType<import("@elaraai/east").IntegerType>;
-            }>;
-        }>;
-        readonly float: import("@elaraai/east").StructType<{
-            readonly fieldId: import("@elaraai/east").StringType;
-            readonly op: import("@elaraai/east").VariantType<{
-                readonly lt: import("@elaraai/east").FloatType;
-                readonly lte: import("@elaraai/east").FloatType;
-                readonly gt: import("@elaraai/east").FloatType;
-                readonly gte: import("@elaraai/east").FloatType;
-            }>;
-        }>;
-        readonly datetime: import("@elaraai/east").StructType<{
-            readonly fieldId: import("@elaraai/east").StringType;
-            readonly op: import("@elaraai/east").VariantType<{
-                readonly before: import("@elaraai/east").DateTimeType;
-                readonly after: import("@elaraai/east").DateTimeType;
-                readonly between: import("@elaraai/east").StructType<{
-                    readonly from: import("@elaraai/east").DateTimeType;
-                    readonly to: import("@elaraai/east").DateTimeType;
-                }>;
-            }>;
-        }>;
-        readonly boolean: import("@elaraai/east").StructType<{
-            readonly fieldId: import("@elaraai/east").StringType;
-            readonly op: import("@elaraai/east").VariantType<{
-                readonly is: import("@elaraai/east").BooleanType;
-            }>;
-        }>;
-    }>>>;
+    readonly common_causes: ArrayType<StringType>;
+    readonly categorical: OptionType<ArrayType<StringType>>;
     readonly method: OptionType<VariantType<{
         readonly linear_regression: NullType;
         readonly propensity_score_weighting: StructType<{
@@ -196,277 +102,369 @@ export declare const ExperimentSpecType: StructType<{
             }>>;
         }>;
     }>>;
-    readonly targetUnits: OptionType<VariantType<{
+    readonly estimand: OptionType<VariantType<{
         readonly ate: NullType;
         readonly att: NullType;
         readonly atc: NullType;
     }>>;
-    readonly trim: OptionType<VariantType<{
-        readonly overlap: NullType;
-        readonly bounds: StructType<{
-            readonly lower: FloatType;
-            readonly upper: FloatType;
-        }>;
+    readonly refute: OptionType<StructType<{
+        /** Permuted-treatment negative control — a real effect should vanish. */
+        readonly placebo: BooleanType;
+        /** Inject an independent random common cause — the effect should hold. */
+        readonly random_common_cause: BooleanType;
+        /** Re-estimate on random subsamples — the effect should be stable. */
+        readonly data_subset: BooleanType;
+        /** Unobserved-confounder strengths to simulate → the sensitivity / tipping curve. */
+        readonly sensitivity: OptionType<ArrayType<FloatType>>;
     }>>;
+    /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+    readonly dose_feature: OptionType<StringType>;
+    readonly min_overlap: OptionType<FloatType>;
+    readonly min_treatment_variation: OptionType<FloatType>;
+    readonly bootstrap: OptionType<StructType<{
+        readonly reps: IntegerType;
+        readonly cluster_column: OptionType<StringType>;
+        readonly confidence_level: OptionType<FloatType>;
+    }>>;
+    readonly random_state: OptionType<IntegerType>;
 }>;
-/** Type alias for {@link ExperimentSpecType}. */
-export type ExperimentSpecType = typeof ExperimentSpecType;
-/**
- * A confidence interval. Structurally identical to the causal library's `ci`,
- * so it unifies by shape across the package boundary.
- *
- * @property lower - Lower bound.
- * @property upper - Upper bound.
- */
-export declare const CiType: StructType<{
-    readonly lower: FloatType;
-    readonly upper: FloatType;
-}>;
-/** Type alias for {@link CiType}. */
-export type CiType = typeof CiType;
-/**
- * One confounder's before-adjustment imbalance — the two group means and the
- * standardised difference. The renderer derives the bar width, tone and "6.1 vs
- * 8.0" label from these numbers.
- *
- * @property column - The confounder column.
- * @property treatedMean - Mean of the column in the treated group.
- * @property controlMean - Mean of the column in the control group.
- * @property stdDiff - Standardised mean difference (the imbalance magnitude).
- */
+/** Type alias for {@link ExperimentConfigType}. */
+export type ExperimentConfigType = typeof ExperimentConfigType;
+/** One confounder's before-adjustment imbalance (categoricals → one row per level). */
 export declare const BalanceRowType: StructType<{
     readonly column: StringType;
-    readonly treatedMean: FloatType;
-    readonly controlMean: FloatType;
-    readonly stdDiff: FloatType;
+    /** The original confounder this row belongs to — equals `column` for a numeric
+     *  confounder; the base confounder for a one-hot categorical level. */
+    readonly base_column: StringType;
+    readonly treated_mean: FloatType;
+    readonly control_mean: FloatType;
+    readonly std_diff: FloatType;
 }>;
 /** Type alias for {@link BalanceRowType}. */
 export type BalanceRowType = typeof BalanceRowType;
+/** Positivity / common-support diagnostic (binary treatment). */
+export declare const OverlapDiagnosticType: StructType<{
+    readonly treated_propensity: VectorType<FloatType>;
+    readonly control_propensity: VectorType<FloatType>;
+    readonly common_support_frac: FloatType;
+    readonly positivity_ok: BooleanType;
+}>;
+/** Type alias for {@link OverlapDiagnosticType}. */
+export type OverlapDiagnosticType = typeof OverlapDiagnosticType;
+/** The robustness summary the verdict + trust tab consume. */
+export declare const RefutationType: StructType<{
+    /** Effect under a permuted (placebo) treatment — should be ≈ 0. */
+    readonly placebo_effect: OptionType<FloatType>;
+    /** Whether the placebo effect vanished. */
+    readonly placebo_passes: OptionType<BooleanType>;
+    /** Whether a decoy random common cause left the estimate inside its CI. */
+    readonly random_cc_within_ci: OptionType<BooleanType>;
+    /** Mean effect across data subsamples (stability). */
+    readonly data_subset_effect: OptionType<FloatType>;
+    /** Std of the effect across data subsamples. */
+    readonly data_subset_std: OptionType<FloatType>;
+    /** Closed-form E-value — confounder strength needed to explain the effect away. */
+    readonly robustness_value: OptionType<FloatType>;
+    /** Unobserved-confounder sensitivity (tipping) curve: effect at each simulated strength. */
+    readonly sensitivity: OptionType<StructType<{
+        readonly strengths: VectorType<FloatType>;
+        readonly effects: VectorType<FloatType>;
+    }>>;
+}>;
+/** Type alias for {@link RefutationType}. */
+export type RefutationType = typeof RefutationType;
+/** A dose-response (ALE) curve of a continuous feature on the outcome. */
+export declare const DoseResponseType: StructType<{
+    readonly feature: StringType;
+    readonly grid: VectorType<FloatType>;
+    readonly effect: VectorType<FloatType>;
+    readonly lower: OptionType<VectorType<FloatType>>;
+    readonly upper: OptionType<VectorType<FloatType>>;
+    /** Rows per dose bin — drives the surface's "you are here" (busiest bin) marker. */
+    readonly size: VectorType<IntegerType>;
+}>;
+/** Type alias for {@link DoseResponseType}. */
+export type DoseResponseType = typeof DoseResponseType;
 /**
- * The `estimate` answer — the adjusted (like-for-like) effect, the naive (raw)
- * effect for the sign-flip comparison, the sample accounting, and the
- * confounder balance. Every word and colour on the surface is derived from
- * these numbers.
- *
- * @property effect - The adjusted (like-for-like) effect estimate.
- * @property ci - Optional confidence interval for `effect`.
- * @property naive - The raw (unadjusted) mean difference.
- * @property naiveCi - Optional confidence interval for `naive`.
- * @property nTotal - Rows in the framed population.
- * @property nTreated - Treated rows used.
- * @property nControl - Control rows used.
- * @property nDropped - Rows dropped by trimming / missing data.
- * @property balance - Per-confounder before-adjustment imbalance, most
- *   imbalanced first.
+ * The honesty verdict — a thin tag; the numbers live top-level on the result.
+ * Only `not_estimable` carries a human-readable reason.
+ */
+export declare const ExperimentVerdictType: VariantType<{
+    readonly causal: NullType;
+    readonly modest: NullType;
+    readonly adjustment_insufficient: NullType;
+    readonly non_identifiable_positivity: NullType;
+    readonly not_estimable: StringType;
+}>;
+/** Type alias for {@link ExperimentVerdictType}. */
+export type ExperimentVerdictType = typeof ExperimentVerdictType;
+/**
+ * The complete, honest result. `adjusted` is `none` when the engine refuses
+ * (positivity / no-variation); the `verdict` tag carries the headline; every
+ * word/colour on the surface is derived from these numbers.
  */
 export declare const ExperimentResultType: StructType<{
-    readonly effect: FloatType;
-    readonly ci: OptionType<StructType<{
-        readonly lower: FloatType;
-        readonly upper: FloatType;
-    }>>;
     readonly naive: FloatType;
-    readonly naiveCi: OptionType<StructType<{
+    readonly naive_ci: OptionType<StructType<{
         readonly lower: FloatType;
         readonly upper: FloatType;
     }>>;
-    readonly nTotal: IntegerType;
-    readonly nTreated: IntegerType;
-    readonly nControl: IntegerType;
-    readonly nDropped: IntegerType;
+    readonly adjusted: OptionType<StructType<{
+        readonly effect: FloatType;
+        readonly ci: OptionType<StructType<{
+            readonly lower: FloatType;
+            readonly upper: FloatType;
+        }>>;
+    }>>;
+    readonly n_total: IntegerType;
+    readonly n_treated: IntegerType;
+    readonly n_control: IntegerType;
+    readonly n_dropped: IntegerType;
     readonly balance: ArrayType<StructType<{
         readonly column: StringType;
-        readonly treatedMean: FloatType;
-        readonly controlMean: FloatType;
-        readonly stdDiff: FloatType;
+        /** The original confounder this row belongs to — equals `column` for a numeric
+         *  confounder; the base confounder for a one-hot categorical level. */
+        readonly base_column: StringType;
+        readonly treated_mean: FloatType;
+        readonly control_mean: FloatType;
+        readonly std_diff: FloatType;
     }>>;
+    readonly overlap: StructType<{
+        readonly treated_propensity: VectorType<FloatType>;
+        readonly control_propensity: VectorType<FloatType>;
+        readonly common_support_frac: FloatType;
+        readonly positivity_ok: BooleanType;
+    }>;
+    readonly refutation: OptionType<StructType<{
+        /** Effect under a permuted (placebo) treatment — should be ≈ 0. */
+        readonly placebo_effect: OptionType<FloatType>;
+        /** Whether the placebo effect vanished. */
+        readonly placebo_passes: OptionType<BooleanType>;
+        /** Whether a decoy random common cause left the estimate inside its CI. */
+        readonly random_cc_within_ci: OptionType<BooleanType>;
+        /** Mean effect across data subsamples (stability). */
+        readonly data_subset_effect: OptionType<FloatType>;
+        /** Std of the effect across data subsamples. */
+        readonly data_subset_std: OptionType<FloatType>;
+        /** Closed-form E-value — confounder strength needed to explain the effect away. */
+        readonly robustness_value: OptionType<FloatType>;
+        /** Unobserved-confounder sensitivity (tipping) curve: effect at each simulated strength. */
+        readonly sensitivity: OptionType<StructType<{
+            readonly strengths: VectorType<FloatType>;
+            readonly effects: VectorType<FloatType>;
+        }>>;
+    }>>;
+    /** ALE dose-response of `dose_feature` (present when `config.dose_feature` is set). */
+    readonly dose_response: OptionType<StructType<{
+        readonly feature: StringType;
+        readonly grid: VectorType<FloatType>;
+        readonly effect: VectorType<FloatType>;
+        readonly lower: OptionType<VectorType<FloatType>>;
+        readonly upper: OptionType<VectorType<FloatType>>;
+        /** Rows per dose bin — drives the surface's "you are here" (busiest bin) marker. */
+        readonly size: VectorType<IntegerType>;
+    }>>;
+    readonly verdict: VariantType<{
+        readonly causal: NullType;
+        readonly modest: NullType;
+        readonly adjustment_insufficient: NullType;
+        readonly non_identifiable_positivity: NullType;
+        readonly not_estimable: StringType;
+    }>;
 }>;
 /** Type alias for {@link ExperimentResultType}. */
 export type ExperimentResultType = typeof ExperimentResultType;
 /**
- * Which robustness check a {@link RefuteCheckType} row is. Closed set → variant;
- * the renderer derives the check's name, description and pass/fail from the kind
- * plus the numbers.
- *
- * @property placebo - Fake treatment — the effect should vanish.
- * @property random_common_cause - Inject a random cause — the effect should hold.
- * @property data_subset - Re-estimate on subsets — the effect should be stable.
- * @property unobserved - Simulated hidden confounder — a sensitivity curve.
+ * Why the trial is sized the way it is — set from the verdict, so the tab's
+ * headline + visuals change with the result rather than reading the same twice.
  */
-export declare const RefuteKindType: VariantType<{
-    readonly placebo: NullType;
-    readonly random_common_cause: NullType;
-    readonly data_subset: NullType;
-    readonly unobserved: NullType;
+export declare const DesignBasisType: VariantType<{
+    /** Clear effect → power the trial to detect the *observed* effect. */
+    readonly detect_observed: NullType;
+    /** Fuzzy / maybe-nothing → power to the smallest effect worth acting on. */
+    readonly resolve_vs_null: NullType;
+    /** A trust check failed → randomise to remove the bias adjustment couldn't. */
+    readonly de_bias: NullType;
+    /** No overlap → randomise within the comparable range. */
+    readonly restrict_to_overlap: NullType;
+    /** No control group exists → hold back a random sample next time. */
+    readonly create_control: NullType;
 }>;
-/** Type alias for {@link RefuteKindType}. */
-export type RefuteKindType = typeof RefuteKindType;
-/**
- * One robustness check — the real refuter numbers. The renderer turns these
- * into the pass/fail row and (for `unobserved`) the sensitivity curve.
- *
- * @property kind - Which check this is ({@link RefuteKindType}).
- * @property estimatedEffect - The original effect being challenged.
- * @property newEffects - Effect(s) under the refutation — one entry for
- *   placebo / random-cause / subset; one per simulated strength for unobserved.
- * @property strengths - For `unobserved` only: the simulated confounder
- *   strengths paired with `newEffects` (the sensitivity-curve x-axis). `none`
- *   for the single-shot checks.
- * @property pValue - Refuter p-value where the check provides one.
- */
-export declare const RefuteCheckType: StructType<{
-    readonly kind: VariantType<{
-        readonly placebo: NullType;
-        readonly random_common_cause: NullType;
-        readonly data_subset: NullType;
-        readonly unobserved: NullType;
-    }>;
-    readonly estimatedEffect: FloatType;
-    readonly newEffects: VectorType<FloatType>;
-    readonly strengths: OptionType<VectorType<FloatType>>;
-    readonly pValue: OptionType<FloatType>;
+/** Type alias for {@link DesignBasisType}. */
+export type DesignBasisType = typeof DesignBasisType;
+/** One sizing option — a split and the head-count it needs (even split first). */
+export declare const TrialOptionType: StructType<{
+    /** Plain label, e.g. "Even split" / "Treat fewer". */
+    readonly label: StringType;
+    /** Fraction assigned to the treatment (0..1; 0.5 = even). */
+    readonly treated_share: FloatType;
+    readonly n_treated: IntegerType;
+    readonly n_control: IntegerType;
+    readonly n_total: IntegerType;
 }>;
-/** Type alias for {@link RefuteCheckType}. */
-export type RefuteCheckType = typeof RefuteCheckType;
+/** Type alias for {@link TrialOptionType}. */
+export type TrialOptionType = typeof TrialOptionType;
+/** The "chance of detecting it" curve — total head-count → power (0..1). */
+export declare const PowerCurveType: StructType<{
+    readonly n: VectorType<IntegerType>;
+    readonly power: VectorType<FloatType>;
+}>;
+/** Type alias for {@link PowerCurveType}. */
+export type PowerCurveType = typeof PowerCurveType;
 /**
- * The `refute` answer — the battery of robustness checks shown in the "Can we
- * trust it?" tab.
- *
- * @property checks - The checks that were run.
+ * The validation-trial recipe — a randomised controlled trial sized from the
+ * observed effect (or the materiality threshold) and the outcome spread, with
+ * the groups matched on the confounders that were most imbalanced. Everything
+ * the "Validate" tab paints is derived from these fields.
  */
-export declare const RefuteResultType: StructType<{
-    readonly checks: ArrayType<StructType<{
-        readonly kind: VariantType<{
-            readonly placebo: NullType;
-            readonly random_common_cause: NullType;
-            readonly data_subset: NullType;
-            readonly unobserved: NullType;
-        }>;
-        readonly estimatedEffect: FloatType;
-        readonly newEffects: VectorType<FloatType>;
-        readonly strengths: OptionType<VectorType<FloatType>>;
-        readonly pValue: OptionType<FloatType>;
+export declare const ExperimentDesignType: StructType<{
+    /** The verdict that drove the recommendation (echoed for framing). */
+    readonly verdict: VariantType<{
+        readonly causal: NullType;
+        readonly modest: NullType;
+        readonly adjustment_insufficient: NullType;
+        readonly non_identifiable_positivity: NullType;
+        readonly not_estimable: StringType;
+    }>;
+    readonly basis: VariantType<{
+        /** Clear effect → power the trial to detect the *observed* effect. */
+        readonly detect_observed: NullType;
+        /** Fuzzy / maybe-nothing → power to the smallest effect worth acting on. */
+        readonly resolve_vs_null: NullType;
+        /** A trust check failed → randomise to remove the bias adjustment couldn't. */
+        readonly de_bias: NullType;
+        /** No overlap → randomise within the comparable range. */
+        readonly restrict_to_overlap: NullType;
+        /** No control group exists → hold back a random sample next time. */
+        readonly create_control: NullType;
+    }>;
+    /** The effect size the trial is powered to detect (observed, or materiality). */
+    readonly target_effect: FloatType;
+    /** Outcome spread (pooled SD) used to size it. */
+    readonly outcome_sd: FloatType;
+    readonly target_power: FloatType;
+    readonly alpha: FloatType;
+    /** Chance the CURRENT sample would already detect `target_effect` (the "you're here" marker); `none` when there's no comparison group. */
+    readonly current_power: OptionType<FloatType>;
+    /** Categories both groups must be matched on (the most-imbalanced confounders). */
+    readonly match_on: ArrayType<StringType>;
+    /** Ranked split options (even split first; cost-saving alternates). */
+    readonly options: ArrayType<StructType<{
+        /** Plain label, e.g. "Even split" / "Treat fewer". */
+        readonly label: StringType;
+        /** Fraction assigned to the treatment (0..1; 0.5 = even). */
+        readonly treated_share: FloatType;
+        readonly n_treated: IntegerType;
+        readonly n_control: IntegerType;
+        readonly n_total: IntegerType;
     }>>;
+    /** The detect-chance curve for the chart. */
+    readonly power_curve: StructType<{
+        readonly n: VectorType<IntegerType>;
+        readonly power: VectorType<FloatType>;
+    }>;
+    /** One generated, plain-language sentence framing the recipe. */
+    readonly rationale: StringType;
+}>;
+/** Type alias for {@link ExperimentDesignType}. */
+export type ExperimentDesignType = typeof ExperimentDesignType;
+/** Optional knobs `Causal.designValidation` accepts (all developer-defaulted). */
+export declare const DesignConfigType: StructType<{
+    /** Significance level (default 0.05). */
+    readonly alpha: OptionType<FloatType>;
+    /** Target chance of detecting the effect (default 0.8). */
+    readonly target_power: OptionType<FloatType>;
+    /** Smallest effect worth acting on — sizes the trial to this when set / when there's no trustworthy observed effect. */
+    readonly materiality: OptionType<FloatType>;
+    /** Treatment shares to offer as options (default [0.5]). */
+    readonly treated_shares: OptionType<ArrayType<FloatType>>;
 }>;
-/** Type alias for {@link RefuteResultType}. */
-export type RefuteResultType = typeof RefuteResultType;
+/** Type alias for {@link DesignConfigType}. */
+export type DesignConfigType = typeof DesignConfigType;
 /**
- * A per-segment dose-response sub-curve (e.g. one production line). The grid /
- * effect / CI vectors mirror the top-level {@link DoseResultType} curve shape.
- *
- * @property label - Segment label ("Line A", "Acme", …).
- * @property grid - Feature grid values.
- * @property effect - Centered ALE effect at each grid value.
- * @property lower - Optional lower CI at each grid value.
- * @property upper - Optional upper CI at each grid value.
+ * The UI-side population filter — a set of {@link Slice} predicates the Step-4
+ * rail edits. It narrows the rows **client-side, before** the `experiment` call,
+ * so it is deliberately **not** a field of {@link ExperimentConfigType} (the
+ * bound function never sees it; the config stays byte-identical to the causal
+ * library's contract). Bound as its own optional staged dataset so a surface can
+ * seed / persist / commit the framing filters.
  */
-export declare const DoseSegmentType: StructType<{
-    readonly label: StringType;
-    readonly grid: VectorType<FloatType>;
-    readonly effect: VectorType<FloatType>;
-    readonly lower: OptionType<VectorType<FloatType>>;
-    readonly upper: OptionType<VectorType<FloatType>>;
-}>;
-/** Type alias for {@link DoseSegmentType}. */
-export type DoseSegmentType = typeof DoseSegmentType;
+export declare const PopulationType: ArrayType<VariantType<{
+    readonly string: import("@elaraai/east").StructType<{
+        readonly fieldId: import("@elaraai/east").StringType;
+        readonly op: import("@elaraai/east").VariantType<{
+            readonly eq: import("@elaraai/east").StringType;
+            readonly neq: import("@elaraai/east").StringType;
+            readonly in: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
+            readonly notIn: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
+            readonly contains: import("@elaraai/east").StringType;
+            readonly matches: import("@elaraai/east").StringType;
+        }>;
+    }>;
+    readonly integer: import("@elaraai/east").StructType<{
+        readonly fieldId: import("@elaraai/east").StringType;
+        readonly op: import("@elaraai/east").VariantType<{
+            readonly eq: import("@elaraai/east").IntegerType;
+            readonly neq: import("@elaraai/east").IntegerType;
+            readonly lt: import("@elaraai/east").IntegerType;
+            readonly lte: import("@elaraai/east").IntegerType;
+            readonly gt: import("@elaraai/east").IntegerType;
+            readonly gte: import("@elaraai/east").IntegerType;
+            readonly in: import("@elaraai/east").SetType<import("@elaraai/east").IntegerType>;
+        }>;
+    }>;
+    readonly float: import("@elaraai/east").StructType<{
+        readonly fieldId: import("@elaraai/east").StringType;
+        readonly op: import("@elaraai/east").VariantType<{
+            readonly lt: import("@elaraai/east").FloatType;
+            readonly lte: import("@elaraai/east").FloatType;
+            readonly gt: import("@elaraai/east").FloatType;
+            readonly gte: import("@elaraai/east").FloatType;
+        }>;
+    }>;
+    readonly datetime: import("@elaraai/east").StructType<{
+        readonly fieldId: import("@elaraai/east").StringType;
+        readonly op: import("@elaraai/east").VariantType<{
+            readonly before: import("@elaraai/east").DateTimeType;
+            readonly after: import("@elaraai/east").DateTimeType;
+            readonly between: import("@elaraai/east").StructType<{
+                readonly from: import("@elaraai/east").DateTimeType;
+                readonly to: import("@elaraai/east").DateTimeType;
+            }>;
+        }>;
+    }>;
+    readonly boolean: import("@elaraai/east").StructType<{
+        readonly fieldId: import("@elaraai/east").StringType;
+        readonly op: import("@elaraai/east").VariantType<{
+            readonly is: import("@elaraai/east").BooleanType;
+        }>;
+    }>;
+}>>;
+/** Type alias for {@link PopulationType}. */
+export type PopulationType = typeof PopulationType;
 /**
- * The `dose` answer — an ALE dose-response curve for a chosen feature, plus the
- * optional per-segment breakdown. The grid / effect / CI / size vectors are
- * structurally identical to the causal library's ALE result.
- *
- * @property feature - The dose feature column.
- * @property grid - Feature grid values (interval edges).
- * @property effect - Centered ALE effect at each grid value (outcome units).
- * @property lower - Optional lower CI at each grid value.
- * @property upper - Optional upper CI at each grid value.
- * @property size - Number of samples in each grid interval.
- * @property segments - Optional per-segment sub-curves ({@link DoseSegmentType}).
+ * Optional per-column display metadata the developer supplies once. Keyed by
+ * column name. Lets the derived prose read "worse" instead of "lower" and show
+ * friendly labels / units.
  */
-export declare const DoseResultType: StructType<{
-    readonly feature: StringType;
-    readonly grid: VectorType<FloatType>;
-    readonly effect: VectorType<FloatType>;
-    readonly lower: OptionType<VectorType<FloatType>>;
-    readonly upper: OptionType<VectorType<FloatType>>;
-    readonly size: VectorType<IntegerType>;
-    readonly segments: OptionType<ArrayType<StructType<{
-        readonly label: StringType;
-        readonly grid: VectorType<FloatType>;
-        readonly effect: VectorType<FloatType>;
-        readonly lower: OptionType<VectorType<FloatType>>;
-        readonly upper: OptionType<VectorType<FloatType>>;
-    }>>>;
-}>;
-/** Type alias for {@link DoseResultType}. */
-export type DoseResultType = typeof DoseResultType;
+export declare const ColumnMetaType: DictType<StringType, StructType<{
+    readonly label: OptionType<StringType>;
+    readonly unit: OptionType<StringType>;
+    readonly higherIsBetter: OptionType<BooleanType>;
+}>>;
+/** Type alias for {@link ColumnMetaType}. */
+export type ColumnMetaType = typeof ColumnMetaType;
 /**
- * A committed experiment in the journal — the framed spec + the headline effect
- * + who committed it when. The renderer derives the verdict words and colour
- * from `effect` / `ci`.
- *
- * @property spec - The experiment that was committed ({@link ExperimentSpecType}).
- * @property effect - The adjusted effect at commit time.
- * @property ci - Optional confidence interval at commit time.
- * @property committedAt - When it was committed.
- * @property committedBy - Who committed it.
+ * A committed experiment in the journal — the framed config + the verdict +
+ * headline effect + who committed it when. The renderer derives the verdict
+ * words and colour from `verdict` / `adjusted`.
  */
 export declare const JournalRowType: StructType<{
-    readonly spec: StructType<{
+    readonly config: StructType<{
         readonly treatment: StringType;
         readonly outcome: StringType;
-        readonly confounders: ArrayType<StringType>;
-        readonly categorical: ArrayType<StringType>;
-        readonly population: OptionType<ArrayType<VariantType<{
-            readonly string: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly eq: import("@elaraai/east").StringType;
-                    readonly neq: import("@elaraai/east").StringType;
-                    readonly in: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                    readonly notIn: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                    readonly contains: import("@elaraai/east").StringType;
-                    readonly matches: import("@elaraai/east").StringType;
-                }>;
-            }>;
-            readonly integer: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly eq: import("@elaraai/east").IntegerType;
-                    readonly neq: import("@elaraai/east").IntegerType;
-                    readonly lt: import("@elaraai/east").IntegerType;
-                    readonly lte: import("@elaraai/east").IntegerType;
-                    readonly gt: import("@elaraai/east").IntegerType;
-                    readonly gte: import("@elaraai/east").IntegerType;
-                    readonly in: import("@elaraai/east").SetType<import("@elaraai/east").IntegerType>;
-                }>;
-            }>;
-            readonly float: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly lt: import("@elaraai/east").FloatType;
-                    readonly lte: import("@elaraai/east").FloatType;
-                    readonly gt: import("@elaraai/east").FloatType;
-                    readonly gte: import("@elaraai/east").FloatType;
-                }>;
-            }>;
-            readonly datetime: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly before: import("@elaraai/east").DateTimeType;
-                    readonly after: import("@elaraai/east").DateTimeType;
-                    readonly between: import("@elaraai/east").StructType<{
-                        readonly from: import("@elaraai/east").DateTimeType;
-                        readonly to: import("@elaraai/east").DateTimeType;
-                    }>;
-                }>;
-            }>;
-            readonly boolean: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly is: import("@elaraai/east").BooleanType;
-                }>;
-            }>;
-        }>>>;
+        readonly common_causes: ArrayType<StringType>;
+        readonly categorical: OptionType<ArrayType<StringType>>;
         readonly method: OptionType<VariantType<{
             readonly linear_regression: NullType;
             readonly propensity_score_weighting: StructType<{
@@ -477,87 +475,53 @@ export declare const JournalRowType: StructType<{
                 }>>;
             }>;
         }>>;
-        readonly targetUnits: OptionType<VariantType<{
+        readonly estimand: OptionType<VariantType<{
             readonly ate: NullType;
             readonly att: NullType;
             readonly atc: NullType;
         }>>;
-        readonly trim: OptionType<VariantType<{
-            readonly overlap: NullType;
-            readonly bounds: StructType<{
-                readonly lower: FloatType;
-                readonly upper: FloatType;
-            }>;
+        readonly refute: OptionType<StructType<{
+            /** Permuted-treatment negative control — a real effect should vanish. */
+            readonly placebo: BooleanType;
+            /** Inject an independent random common cause — the effect should hold. */
+            readonly random_common_cause: BooleanType;
+            /** Re-estimate on random subsamples — the effect should be stable. */
+            readonly data_subset: BooleanType;
+            /** Unobserved-confounder strengths to simulate → the sensitivity / tipping curve. */
+            readonly sensitivity: OptionType<ArrayType<FloatType>>;
         }>>;
+        /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+        readonly dose_feature: OptionType<StringType>;
+        readonly min_overlap: OptionType<FloatType>;
+        readonly min_treatment_variation: OptionType<FloatType>;
+        readonly bootstrap: OptionType<StructType<{
+            readonly reps: IntegerType;
+            readonly cluster_column: OptionType<StringType>;
+            readonly confidence_level: OptionType<FloatType>;
+        }>>;
+        readonly random_state: OptionType<IntegerType>;
     }>;
-    readonly effect: FloatType;
-    readonly ci: OptionType<StructType<{
-        readonly lower: FloatType;
-        readonly upper: FloatType;
-    }>>;
-    readonly committedAt: DateTimeType;
-    readonly committedBy: StringType;
+    readonly verdict: VariantType<{
+        readonly causal: NullType;
+        readonly modest: NullType;
+        readonly adjustment_insufficient: NullType;
+        readonly non_identifiable_positivity: NullType;
+        readonly not_estimable: StringType;
+    }>;
+    readonly naive: FloatType;
+    readonly adjusted: OptionType<FloatType>;
+    readonly committed_at: DateTimeType;
+    readonly committed_by: StringType;
 }>;
 /** Type alias for {@link JournalRowType}. */
 export type JournalRowType = typeof JournalRowType;
 /** The journal dataset — committed experiments, newest first. */
 export declare const JournalType: ArrayType<StructType<{
-    readonly spec: StructType<{
+    readonly config: StructType<{
         readonly treatment: StringType;
         readonly outcome: StringType;
-        readonly confounders: ArrayType<StringType>;
-        readonly categorical: ArrayType<StringType>;
-        readonly population: OptionType<ArrayType<VariantType<{
-            readonly string: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly eq: import("@elaraai/east").StringType;
-                    readonly neq: import("@elaraai/east").StringType;
-                    readonly in: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                    readonly notIn: import("@elaraai/east").SetType<import("@elaraai/east").StringType>;
-                    readonly contains: import("@elaraai/east").StringType;
-                    readonly matches: import("@elaraai/east").StringType;
-                }>;
-            }>;
-            readonly integer: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly eq: import("@elaraai/east").IntegerType;
-                    readonly neq: import("@elaraai/east").IntegerType;
-                    readonly lt: import("@elaraai/east").IntegerType;
-                    readonly lte: import("@elaraai/east").IntegerType;
-                    readonly gt: import("@elaraai/east").IntegerType;
-                    readonly gte: import("@elaraai/east").IntegerType;
-                    readonly in: import("@elaraai/east").SetType<import("@elaraai/east").IntegerType>;
-                }>;
-            }>;
-            readonly float: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly lt: import("@elaraai/east").FloatType;
-                    readonly lte: import("@elaraai/east").FloatType;
-                    readonly gt: import("@elaraai/east").FloatType;
-                    readonly gte: import("@elaraai/east").FloatType;
-                }>;
-            }>;
-            readonly datetime: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly before: import("@elaraai/east").DateTimeType;
-                    readonly after: import("@elaraai/east").DateTimeType;
-                    readonly between: import("@elaraai/east").StructType<{
-                        readonly from: import("@elaraai/east").DateTimeType;
-                        readonly to: import("@elaraai/east").DateTimeType;
-                    }>;
-                }>;
-            }>;
-            readonly boolean: import("@elaraai/east").StructType<{
-                readonly fieldId: import("@elaraai/east").StringType;
-                readonly op: import("@elaraai/east").VariantType<{
-                    readonly is: import("@elaraai/east").BooleanType;
-                }>;
-            }>;
-        }>>>;
+        readonly common_causes: ArrayType<StringType>;
+        readonly categorical: OptionType<ArrayType<StringType>>;
         readonly method: OptionType<VariantType<{
             readonly linear_regression: NullType;
             readonly propensity_score_weighting: StructType<{
@@ -568,44 +532,44 @@ export declare const JournalType: ArrayType<StructType<{
                 }>>;
             }>;
         }>>;
-        readonly targetUnits: OptionType<VariantType<{
+        readonly estimand: OptionType<VariantType<{
             readonly ate: NullType;
             readonly att: NullType;
             readonly atc: NullType;
         }>>;
-        readonly trim: OptionType<VariantType<{
-            readonly overlap: NullType;
-            readonly bounds: StructType<{
-                readonly lower: FloatType;
-                readonly upper: FloatType;
-            }>;
+        readonly refute: OptionType<StructType<{
+            /** Permuted-treatment negative control — a real effect should vanish. */
+            readonly placebo: BooleanType;
+            /** Inject an independent random common cause — the effect should hold. */
+            readonly random_common_cause: BooleanType;
+            /** Re-estimate on random subsamples — the effect should be stable. */
+            readonly data_subset: BooleanType;
+            /** Unobserved-confounder strengths to simulate → the sensitivity / tipping curve. */
+            readonly sensitivity: OptionType<ArrayType<FloatType>>;
+        }>>;
+        /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+        readonly dose_feature: OptionType<StringType>;
+        readonly min_overlap: OptionType<FloatType>;
+        readonly min_treatment_variation: OptionType<FloatType>;
+        readonly bootstrap: OptionType<StructType<{
+            readonly reps: IntegerType;
+            readonly cluster_column: OptionType<StringType>;
+            readonly confidence_level: OptionType<FloatType>;
         }>>;
+        readonly random_state: OptionType<IntegerType>;
     }>;
-    readonly effect: FloatType;
-    readonly ci: OptionType<StructType<{
-        readonly lower: FloatType;
-        readonly upper: FloatType;
-    }>>;
-    readonly committedAt: DateTimeType;
-    readonly committedBy: StringType;
+    readonly verdict: VariantType<{
+        readonly causal: NullType;
+        readonly modest: NullType;
+        readonly adjustment_insufficient: NullType;
+        readonly non_identifiable_positivity: NullType;
+        readonly not_estimable: StringType;
+    }>;
+    readonly naive: FloatType;
+    readonly adjusted: OptionType<FloatType>;
+    readonly committed_at: DateTimeType;
+    readonly committed_by: StringType;
 }>>;
 /** Type alias for {@link JournalType}. */
 export type JournalType = typeof JournalType;
-/**
- * Optional per-column metadata the developer supplies once. Lets the derived
- * prose read "worse" instead of "lower" and show friendly labels / units.
- * Keyed by column name.
- *
- * @property label - Friendly display label for the column.
- * @property unit - Unit suffix ("MPa", "$", …).
- * @property higherIsBetter - Whether a larger value is the good direction —
- *   flips "lower" → "worse" in the derived words.
- */
-export declare const ColumnMetaType: DictType<StringType, StructType<{
-    readonly label: OptionType<StringType>;
-    readonly unit: OptionType<StringType>;
-    readonly higherIsBetter: OptionType<BooleanType>;
-}>>;
-/** Type alias for {@link ColumnMetaType}. */
-export type ColumnMetaType = typeof ColumnMetaType;
 //# sourceMappingURL=types.d.ts.map