@elaraai/east-py-datascience 1.0.11 → 1.0.13

package/dist/src/causal/causal.d.ts

@@ -5,15 +5,18 @@
 /**
  * Causal inference for East.
  *
- * Provides causal effect estimation (DoWhy backdoor adjustment),
- * refutation tests, heterogeneous treatment effects (EconML LinearDML),
- * and accumulated local effects dose-response curves (PyALE).
+ * One declarative entry point — {@link Causal.experiment} — answers *"did X
+ * change Y, and can I trust it?"* for a binary treatment: the naive vs
+ * backdoor-adjusted effect, confounder balance, propensity overlap, a
+ * robustness check, and an honesty **verdict** that refuses (`adjusted = none`)
+ * when the data can't support an answer. The raw DoWhy / EconML / PyALE
+ * estimators are internal implementation it composes — not a public surface.
  *
  * @packageDocumentation
  */
-import { StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, StringType, BlobType, NullType } from "@elaraai/east";
-import { VectorType, MatrixType } from "../types.js";
-export { VectorType, MatrixType } from "../types.js";
+import { StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, StringType, NullType } from "@elaraai/east";
+import { VectorType } from "../types.js";
+export { VectorType } from "../types.js";
 /**
  * Inverse propensity weighting scheme for the propensity score
  * weighting estimator.
@@ -30,7 +33,7 @@ export declare const CausalWeightingSchemeType: VariantType<{
  * Backdoor-adjusted effect estimator.
  */
 export declare const CausalEstimatorType: VariantType<{
-    /** Linear regression of outcome on treatment + common causes */
+    /** Linear regression of outcome on treatment + common causes (default) */
     readonly linear_regression: NullType;
     /** Inverse propensity score weighting (binary treatment only) */
     readonly propensity_score_weighting: StructType<{
@@ -56,58 +59,56 @@ export declare const CausalTargetUnitsType: VariantType<{
     /** Average treatment effect on the controls */
     readonly atc: NullType;
 }>;
-/**
- * Propensity-based sample trimming applied before estimation
- * (propensity score weighting only).
- */
-export declare const PropensityTrimType: VariantType<{
-    /** Keep units inside the common-support overlap of treated and control propensities */
-    readonly overlap: NullType;
-    /** Keep units with propensity inside explicit bounds */
-    readonly bounds: StructType<{
-        /** Minimum propensity score to keep */
-        readonly lower: FloatType;
-        /** Maximum propensity score to keep */
-        readonly upper: FloatType;
-    }>;
-}>;
 /**
  * Bootstrap confidence interval configuration.
  *
- * When `cluster_column` is set, whole clusters are resampled with
- * replacement (the cluster is the exchangeable unit) — use this when rows
- * are autocorrelated within a group (e.g. days within a batch).
+ * When `cluster_column` is set, whole clusters are resampled with replacement
+ * (the cluster is the exchangeable unit) — use this when rows are autocorrelated
+ * within a group.
  */
 export declare const CausalBootstrapConfigType: StructType<{
-    /** Number of bootstrap replicates */
+    /** Number of bootstrap replicates (default 200) */
     readonly reps: IntegerType;
     /** Column whose values identify clusters to resample (default: resample rows) */
     readonly cluster_column: OptionType<StringType>;
     /** Confidence level for the percentile interval (default 0.95) */
     readonly confidence_level: OptionType<FloatType>;
 }>;
+/** A confidence interval — the one CI type used across the result. */
+export declare const CiType: StructType<{
+    readonly lower: FloatType;
+    readonly upper: FloatType;
+}>;
 /**
- * Configuration for backdoor-adjusted causal effect estimation.
- *
- * The data matrix is interpreted via `columns`: every column referenced by
- * `treatment`, `outcome`, `common_causes`, `categorical` and
- * `bootstrap.cluster_column` must appear in `columns`. Categorical columns
- * hold integer-valued category codes and are one-hot encoded internally.
+ * Which robustness checks to run inside {@link causal_experiment}.
+ */
+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>>;
+}>;
+/**
+ * Configuration for {@link causal_experiment} — the staged "question + method"
+ * the surface edits. Binary treatment only (v1). Reuses the estimator / target
+ * / bootstrap vocabularies.
  */
-export declare const CausalEffectConfigType: StructType<{
-    /** Column names for the data matrix (one per column, in order) */
-    readonly columns: ArrayType<StringType>;
-    /** Treatment column (must be 0/1 for propensity score weighting) */
+export declare const CausalExperimentConfigType: StructType<{
+    /** Binary (0/1) treatment column. */
     readonly treatment: StringType;
-    /** Outcome column */
+    /** Outcome column. */
     readonly outcome: StringType;
-    /** Confounder columns to adjust for (the backdoor set) */
+    /** Confounders to adjust for (the backdoor set). */
     readonly common_causes: ArrayType<StringType>;
-    /** Columns holding integer category codes, one-hot encoded internally */
+    /** Confounder columns holding categories (string or int codes), one-hot encoded. */
     readonly categorical: OptionType<ArrayType<StringType>>;
-    /** Effect estimator (default: linear_regression) */
+    /** Estimator (default: linear_regression). */
     readonly method: OptionType<VariantType<{
-        /** Linear regression of outcome on treatment + common causes */
+        /** Linear regression of outcome on treatment + common causes (default) */
         readonly linear_regression: NullType;
         /** Inverse propensity score weighting (binary treatment only) */
         readonly propensity_score_weighting: StructType<{
@@ -122,8 +123,8 @@ export declare const CausalEffectConfigType: StructType<{
             }>>;
         }>;
     }>>;
-    /** Target population (default: ate) */
-    readonly target_units: OptionType<VariantType<{
+    /** Target population (default: ate). */
+    readonly estimand: OptionType<VariantType<{
         /** Average treatment effect over all units */
         readonly ate: NullType;
         /** Average treatment effect on the treated */
@@ -131,281 +132,211 @@ export declare const CausalEffectConfigType: StructType<{
         /** Average treatment effect on the controls */
         readonly atc: NullType;
     }>>;
-    /** Propensity trimming applied before estimation (psw only) */
-    readonly trim: OptionType<VariantType<{
-        /** Keep units inside the common-support overlap of treated and control propensities */
-        readonly overlap: NullType;
-        /** Keep units with propensity inside explicit bounds */
-        readonly bounds: StructType<{
-            /** Minimum propensity score to keep */
-            readonly lower: FloatType;
-            /** Maximum propensity score to keep */
-            readonly upper: FloatType;
-        }>;
+    /** Which robustness checks to run. */
+    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>>;
     }>>;
-    /** Bootstrap confidence interval (omit to skip CI computation) */
+    /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+    readonly dose_feature: OptionType<StringType>;
+    /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+    readonly min_overlap: OptionType<FloatType>;
+    /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+    readonly min_treatment_variation: OptionType<FloatType>;
+    /** Bootstrap CI config (default: 200 reps, 0.95). */
     readonly bootstrap: OptionType<StructType<{
-        /** Number of bootstrap replicates */
+        /** Number of bootstrap replicates (default 200) */
         readonly reps: IntegerType;
         /** Column whose values identify clusters to resample (default: resample rows) */
         readonly cluster_column: OptionType<StringType>;
         /** Confidence level for the percentile interval (default 0.95) */
         readonly confidence_level: OptionType<FloatType>;
     }>>;
-    /** Random seed for propensity fitting and bootstrap resampling */
+    /** Random seed. */
     readonly random_state: OptionType<IntegerType>;
 }>;
-/**
- * Refutation test for an estimated causal effect.
- */
-export declare const CausalRefuterType: VariantType<{
-    /** Replace treatment with a permuted placebo - effect should vanish */
-    readonly placebo_treatment: StructType<{
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /** Add an independent random common cause - effect should be unchanged */
-    readonly random_common_cause: StructType<{
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /** Re-estimate on random data subsets - effect should be stable */
-    readonly data_subset: StructType<{
-        /** Fraction of rows kept per simulation (default 0.8) */
-        readonly subset_fraction: OptionType<FloatType>;
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /**
-     * Simulate an unobserved confounder at each given strength - a
-     * sensitivity/tipping curve. Strength acts on both treatment
-     * (flip probability for binary treatment, linear coefficient otherwise)
-     * and outcome (linear coefficient).
-     */
-    readonly unobserved_common_cause: StructType<{
-        /** Confounder effect strengths to simulate, one new effect per entry */
-        readonly effect_strengths: ArrayType<FloatType>;
-    }>;
+/** One confounder's before-adjustment imbalance (categoricals → one row per level). */
+export declare const BalanceRowType: StructType<{
+    readonly column: StringType;
+    /** 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;
+    /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+    readonly std_diff: FloatType;
 }>;
-/**
- * Nuisance model for DML residualization stages.
- */
-export declare const CausalNuisanceModelType: VariantType<{
-    /** Random forest (regressor, or classifier for a discrete treatment) */
-    readonly random_forest: StructType<{
-        /** Number of trees (default 100) */
-        readonly n_estimators: OptionType<IntegerType>;
-        /** Minimum samples per leaf (default 5) */
-        readonly min_samples_leaf: OptionType<IntegerType>;
-        /** Maximum tree depth (default unlimited) */
-        readonly max_depth: OptionType<IntegerType>;
-    }>;
-    /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-    readonly gradient_boosting: StructType<{
-        /** Number of boosting stages (default 100) */
-        readonly n_estimators: OptionType<IntegerType>;
-        /** Learning rate (default 0.1) */
-        readonly learning_rate: OptionType<FloatType>;
-        /** Maximum tree depth (default 3) */
-        readonly max_depth: OptionType<IntegerType>;
-    }>;
-    /** Linear/logistic regression */
-    readonly linear: NullType;
+/** Positivity / common-support diagnostic (binary treatment). */
+export declare const OverlapDiagnosticType: StructType<{
+    /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+    readonly treated_propensity: VectorType<FloatType>;
+    /** Propensity histogram for the control arm. */
+    readonly control_propensity: VectorType<FloatType>;
+    /** Fraction of rows inside the treated/control common support. */
+    readonly common_support_frac: FloatType;
+    /** Whether common support clears `min_overlap`. */
+    readonly positivity_ok: BooleanType;
 }>;
-/**
- * Configuration for double machine learning (EconML LinearDML).
- */
-export declare const CausalDMLConfigType: StructType<{
-    /** Nuisance model for the outcome stage (default: random_forest) */
-    readonly model_y: OptionType<VariantType<{
-        /** Random forest (regressor, or classifier for a discrete treatment) */
-        readonly random_forest: StructType<{
-            /** Number of trees (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 5) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-        readonly gradient_boosting: StructType<{
-            /** Number of boosting stages (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.1) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default 3) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Linear/logistic regression */
-        readonly linear: NullType;
+/** 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>;
     }>>;
-    /** Nuisance model for the treatment stage (default: random_forest) */
-    readonly model_t: OptionType<VariantType<{
-        /** Random forest (regressor, or classifier for a discrete treatment) */
-        readonly random_forest: StructType<{
-            /** Number of trees (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 5) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-        readonly gradient_boosting: StructType<{
-            /** Number of boosting stages (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.1) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default 3) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Linear/logistic regression */
-        readonly linear: NullType;
-    }>>;
-    /** Treat the treatment as discrete/categorical (default false) */
-    readonly discrete_treatment: OptionType<BooleanType>;
-    /** Cross-fitting folds (default 2) */
-    readonly cv_folds: OptionType<IntegerType>;
-    /** Confidence level for effect/ATE intervals (default 0.95) */
-    readonly confidence_level: OptionType<FloatType>;
-    /** Random seed */
-    readonly random_state: OptionType<IntegerType>;
 }>;
-/**
- * Configuration for an accumulated local effects (ALE) dose-response curve.
- *
- * Fits a gradient-boosting emulator of the outcome on all non-outcome
- * columns, then computes the correlation-robust ALE curve of `feature`.
- */
-export declare const CausalALEConfigType: StructType<{
-    /** Column names for the data matrix (one per column, in order) */
-    readonly columns: ArrayType<StringType>;
-    /** Outcome column the emulator predicts */
-    readonly outcome: StringType;
-    /** Continuous feature column to compute the ALE curve for */
+/** A dose-response (ALE) curve of a continuous feature on the outcome. */
+export declare const DoseResponseType: StructType<{
     readonly feature: StringType;
-    /** Columns holding integer category codes, one-hot encoded internally */
-    readonly categorical: OptionType<ArrayType<StringType>>;
-    /** Number of grid intervals (default 10) */
-    readonly grid_size: OptionType<IntegerType>;
-    /** Include confidence intervals (default true) */
-    readonly include_ci: OptionType<BooleanType>;
-    /** Confidence level for the CI (default 0.95) */
-    readonly confidence_level: OptionType<FloatType>;
-    /** Emulator (HistGradientBoosting) hyperparameters */
-    readonly emulator: OptionType<StructType<{
-        /** Number of boosting iterations (default 300) */
-        readonly n_estimators: OptionType<IntegerType>;
-        /** Learning rate (default 0.05) */
-        readonly learning_rate: OptionType<FloatType>;
-        /** Maximum tree depth (default unlimited) */
-        readonly max_depth: OptionType<IntegerType>;
-        /** Minimum samples per leaf (default 20; lower for small datasets) */
-        readonly min_samples_leaf: OptionType<IntegerType>;
-    }>>;
-    /** Random seed for the emulator */
-    readonly random_state: OptionType<IntegerType>;
+    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>;
 }>;
 /**
- * Model blob for a fitted LinearDML estimator.
+ * 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 CausalDMLModelBlobType: VariantType<{
-    /** Fitted EconML LinearDML estimator */
-    readonly causal_dml: StructType<{
-        /** Serialized estimator (cloudpickle) */
-        readonly data: BlobType;
-        /** Number of effect-modifier (X) features */
-        readonly n_features_x: IntegerType;
-        /** Confidence level used for effect/ATE intervals */
-        readonly confidence_level: FloatType;
-    }>;
+export declare const ExperimentVerdictType: VariantType<{
+    /** A real, robust, material effect. */
+    readonly causal: NullType;
+    /** A small but real effect, or no clear effect after adjustment. */
+    readonly modest: NullType;
+    /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+    readonly adjustment_insufficient: NullType;
+    /** No like-for-like comparison exists (positivity violated). */
+    readonly non_identifiable_positivity: NullType;
+    /** The estimand can't be formed (treatment barely varies). */
+    readonly not_estimable: StringType;
 }>;
 /**
- * Estimated causal effect.
+ * The complete, honest result of {@link causal_experiment}. `adjusted` is
+ * `none` when the engine refuses (positivity / no-variation); the `verdict` tag
+ * carries the headline; every word/colour on the surface derives from these numbers.
  */
-export declare const CausalEffectResultType: StructType<{
-    /** Point estimate of the effect (outcome units per treatment unit) */
-    readonly effect: FloatType;
-    /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-    readonly ci: OptionType<StructType<{
-        /** Lower bound */
+export declare const CausalExperimentResultType: StructType<{
+    /** The raw (unadjusted) mean difference — always computable. */
+    readonly naive: FloatType;
+    readonly naive_ci: OptionType<StructType<{
         readonly lower: FloatType;
-        /** Upper bound */
         readonly upper: FloatType;
     }>>;
-    /** Rows used for estimation (after trimming) */
-    readonly n_samples: IntegerType;
-    /** Treated rows used */
+    /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+    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;
-    /** Control rows used */
     readonly n_control: IntegerType;
+    readonly n_dropped: IntegerType;
+    /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+    readonly balance: ArrayType<StructType<{
+        readonly column: StringType;
+        /** 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;
+        /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+        readonly std_diff: FloatType;
+    }>>;
+    readonly overlap: StructType<{
+        /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+        readonly treated_propensity: VectorType<FloatType>;
+        /** Propensity histogram for the control arm. */
+        readonly control_propensity: VectorType<FloatType>;
+        /** Fraction of rows inside the treated/control common support. */
+        readonly common_support_frac: FloatType;
+        /** Whether common support clears `min_overlap`. */
+        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<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        readonly not_estimable: StringType;
+    }>;
 }>;
 /**
- * Refutation test result.
- */
-export declare const CausalRefuteResultType: StructType<{
-    /** The original estimated effect being refuted */
-    readonly estimated_effect: FloatType;
-    /**
-     * Effect under the refutation. One entry for placebo/random-common-cause/
-     * data-subset; one entry per strength for unobserved_common_cause.
-     */
-    readonly new_effects: VectorType<FloatType>;
-    /** Refutation p-value where the refuter provides one */
-    readonly p_value: OptionType<FloatType>;
-}>;
-/**
- * Average treatment effect with confidence interval.
- */
-export declare const CausalATEResultType: StructType<{
-    /** Average treatment effect over the given X */
-    readonly ate: FloatType;
-    /** Lower bound at the model's confidence level */
-    readonly lower: FloatType;
-    /** Upper bound at the model's confidence level */
-    readonly upper: FloatType;
-}>;
-/**
- * Accumulated local effects curve.
- */
-export declare const ALEResultType: StructType<{
-    /** Feature grid values (interval edges) */
-    readonly grid: VectorType<FloatType>;
-    /** Centered ALE effect at each grid value (outcome units) */
-    readonly effect: VectorType<FloatType>;
-    /** Lower CI at each grid value (present when include_ci) */
-    readonly lower: OptionType<VectorType<FloatType>>;
-    /** Upper CI at each grid value (present when include_ci) */
-    readonly upper: OptionType<VectorType<FloatType>>;
-    /** Number of samples in each grid interval */
-    readonly size: VectorType<IntegerType>;
-}>;
-/**
- * Estimate a backdoor-adjusted causal effect of treatment on outcome.
- *
- * Identifies the effect with DoWhy given the common causes, then estimates
- * it by linear regression or inverse propensity score weighting. Optionally
- * trims to propensity common support and computes a (cluster) bootstrap
- * confidence interval.
+ * One declarative causal experiment — naive vs adjusted effect, balance,
+ * overlap, robustness, and an honesty verdict, in a single call. Generic over
+ * the row struct (fields = columns), binary treatment.
  *
- * @param data - Data matrix (rows = units, columns named by config.columns)
- * @param config - Estimation configuration
- * @returns Effect estimate with optional CI and sample counts
+ * @param data - Array of row structs (one per unit; fields are the columns)
+ * @param config - The experiment configuration
+ * @returns The honest result + verdict; `adjusted` is `none` when refused
  */
-export declare const causal_effect: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-    /** Column names for the data matrix (one per column, in order) */
-    readonly columns: ArrayType<StringType>;
-    /** Treatment column (must be 0/1 for propensity score weighting) */
+export declare const causal_experiment: import("@elaraai/east").GenericPlatformDefinition<readonly ["T"], readonly [ArrayType<unknown>, StructType<{
+    /** Binary (0/1) treatment column. */
     readonly treatment: StringType;
-    /** Outcome column */
+    /** Outcome column. */
     readonly outcome: StringType;
-    /** Confounder columns to adjust for (the backdoor set) */
+    /** Confounders to adjust for (the backdoor set). */
     readonly common_causes: ArrayType<StringType>;
-    /** Columns holding integer category codes, one-hot encoded internally */
+    /** Confounder columns holding categories (string or int codes), one-hot encoded. */
     readonly categorical: OptionType<ArrayType<StringType>>;
-    /** Effect estimator (default: linear_regression) */
+    /** Estimator (default: linear_regression). */
     readonly method: OptionType<VariantType<{
-        /** Linear regression of outcome on treatment + common causes */
+        /** Linear regression of outcome on treatment + common causes (default) */
         readonly linear_regression: NullType;
         /** Inverse propensity score weighting (binary treatment only) */
         readonly propensity_score_weighting: StructType<{
@@ -420,8 +351,8 @@ export declare const causal_effect: import("@elaraai/east").PlatformDefinition<[
             }>>;
         }>;
     }>>;
-    /** Target population (default: ate) */
-    readonly target_units: OptionType<VariantType<{
+    /** Target population (default: ate). */
+    readonly estimand: OptionType<VariantType<{
         /** Average treatment effect over all units */
         readonly ate: NullType;
         /** Average treatment effect on the treated */
@@ -429,72 +360,236 @@ export declare const causal_effect: import("@elaraai/east").PlatformDefinition<[
         /** Average treatment effect on the controls */
         readonly atc: NullType;
     }>>;
-    /** Propensity trimming applied before estimation (psw only) */
-    readonly trim: OptionType<VariantType<{
-        /** Keep units inside the common-support overlap of treated and control propensities */
-        readonly overlap: NullType;
-        /** Keep units with propensity inside explicit bounds */
-        readonly bounds: StructType<{
-            /** Minimum propensity score to keep */
-            readonly lower: FloatType;
-            /** Maximum propensity score to keep */
-            readonly upper: FloatType;
-        }>;
+    /** Which robustness checks to run. */
+    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>>;
     }>>;
-    /** Bootstrap confidence interval (omit to skip CI computation) */
+    /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+    readonly dose_feature: OptionType<StringType>;
+    /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+    readonly min_overlap: OptionType<FloatType>;
+    /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+    readonly min_treatment_variation: OptionType<FloatType>;
+    /** Bootstrap CI config (default: 200 reps, 0.95). */
     readonly bootstrap: OptionType<StructType<{
-        /** Number of bootstrap replicates */
+        /** Number of bootstrap replicates (default 200) */
         readonly reps: IntegerType;
         /** Column whose values identify clusters to resample (default: resample rows) */
         readonly cluster_column: OptionType<StringType>;
         /** Confidence level for the percentile interval (default 0.95) */
         readonly confidence_level: OptionType<FloatType>;
     }>>;
-    /** Random seed for propensity fitting and bootstrap resampling */
+    /** Random seed. */
     readonly random_state: OptionType<IntegerType>;
 }>], StructType<{
-    /** Point estimate of the effect (outcome units per treatment unit) */
-    readonly effect: FloatType;
-    /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-    readonly ci: OptionType<StructType<{
-        /** Lower bound */
+    /** The raw (unadjusted) mean difference — always computable. */
+    readonly naive: FloatType;
+    readonly naive_ci: OptionType<StructType<{
         readonly lower: FloatType;
-        /** Upper bound */
         readonly upper: FloatType;
     }>>;
-    /** Rows used for estimation (after trimming) */
-    readonly n_samples: IntegerType;
-    /** Treated rows used */
+    /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+    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;
-    /** Control rows used */
     readonly n_control: IntegerType;
+    readonly n_dropped: IntegerType;
+    /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+    readonly balance: ArrayType<StructType<{
+        readonly column: StringType;
+        /** 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;
+        /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+        readonly std_diff: FloatType;
+    }>>;
+    readonly overlap: StructType<{
+        /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+        readonly treated_propensity: VectorType<FloatType>;
+        /** Propensity histogram for the control arm. */
+        readonly control_propensity: VectorType<FloatType>;
+        /** Fraction of rows inside the treated/control common support. */
+        readonly common_support_frac: FloatType;
+        /** Whether common support clears `min_overlap`. */
+        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<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        readonly not_estimable: StringType;
+    }>;
 }>>;
+/** Why the trial is sized the way it is — set from the verdict. */
+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;
+}>;
+/** One sizing option — a split and the head-count it needs (even split first). */
+export declare const TrialOptionType: StructType<{
+    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 "chance of detecting it" curve — total head-count → power (0..1). */
+export declare const PowerCurveType: StructType<{
+    readonly n: VectorType<IntegerType>;
+    readonly power: VectorType<FloatType>;
+}>;
 /**
- * Refute an estimated causal effect.
- *
- * Re-estimates the effect from `config`, then applies the given refuter
- * (placebo treatment, random common cause, data subset, or simulated
- * unobserved confounder sensitivity curve).
+ * 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.
+ */
+export declare const ExperimentDesignType: StructType<{
+    readonly verdict: VariantType<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        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;
+    }>;
+    /** 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`; `none` when there's no comparison group. */
+    readonly current_power: OptionType<FloatType>;
+    /** Categories both groups must be matched on (most-imbalanced confounders). */
+    readonly match_on: ArrayType<StringType>;
+    /** Ranked split options (even split first; cost-saving alternates). */
+    readonly options: ArrayType<StructType<{
+        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;
+}>;
+/** Optional knobs for {@link causal_design_validation} (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>>;
+}>;
+/**
+ * Design the real controlled trial that would validate a finished experiment.
+ * Generic over the row struct (same as {@link causal_experiment}); takes the data,
+ * the experiment config, the experiment result, and optional design knobs, and
+ * returns the trial recipe (sample size, split options, match-on categories, the
+ * power curve, and a plain-language rationale).
  *
- * @param data - Data matrix (rows = units, columns named by config.columns)
- * @param config - Estimation configuration (same as causal_effect)
- * @param refuter - Refutation test to apply
- * @returns Original effect, refuted effect(s), and p-value where available
+ * @param data - The rows the experiment ran on
+ * @param config - The experiment configuration (names treatment / outcome / confounders)
+ * @param result - The {@link causal_experiment} result whose verdict drives the recipe
+ * @param design_config - Optional alpha / power / materiality / split knobs
+ * @returns The validation-trial recipe
  */
-export declare const causal_refute: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-    /** Column names for the data matrix (one per column, in order) */
-    readonly columns: ArrayType<StringType>;
-    /** Treatment column (must be 0/1 for propensity score weighting) */
+export declare const causal_design_validation: import("@elaraai/east").GenericPlatformDefinition<readonly ["T"], readonly [ArrayType<unknown>, StructType<{
+    /** Binary (0/1) treatment column. */
     readonly treatment: StringType;
-    /** Outcome column */
+    /** Outcome column. */
     readonly outcome: StringType;
-    /** Confounder columns to adjust for (the backdoor set) */
+    /** Confounders to adjust for (the backdoor set). */
     readonly common_causes: ArrayType<StringType>;
-    /** Columns holding integer category codes, one-hot encoded internally */
+    /** Confounder columns holding categories (string or int codes), one-hot encoded. */
     readonly categorical: OptionType<ArrayType<StringType>>;
-    /** Effect estimator (default: linear_regression) */
+    /** Estimator (default: linear_regression). */
     readonly method: OptionType<VariantType<{
-        /** Linear regression of outcome on treatment + common causes */
+        /** Linear regression of outcome on treatment + common causes (default) */
         readonly linear_regression: NullType;
         /** Inverse propensity score weighting (binary treatment only) */
         readonly propensity_score_weighting: StructType<{
@@ -509,8 +604,8 @@ export declare const causal_refute: import("@elaraai/east").PlatformDefinition<[
             }>>;
         }>;
     }>>;
-    /** Target population (default: ate) */
-    readonly target_units: OptionType<VariantType<{
+    /** Target population (default: ate). */
+    readonly estimand: OptionType<VariantType<{
         /** Average treatment effect over all units */
         readonly ate: NullType;
         /** Average treatment effect on the treated */
@@ -518,244 +613,177 @@ export declare const causal_refute: import("@elaraai/east").PlatformDefinition<[
         /** Average treatment effect on the controls */
         readonly atc: NullType;
     }>>;
-    /** Propensity trimming applied before estimation (psw only) */
-    readonly trim: OptionType<VariantType<{
-        /** Keep units inside the common-support overlap of treated and control propensities */
-        readonly overlap: NullType;
-        /** Keep units with propensity inside explicit bounds */
-        readonly bounds: StructType<{
-            /** Minimum propensity score to keep */
-            readonly lower: FloatType;
-            /** Maximum propensity score to keep */
-            readonly upper: FloatType;
-        }>;
+    /** Which robustness checks to run. */
+    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>>;
     }>>;
-    /** Bootstrap confidence interval (omit to skip CI computation) */
+    /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+    readonly dose_feature: OptionType<StringType>;
+    /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+    readonly min_overlap: OptionType<FloatType>;
+    /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+    readonly min_treatment_variation: OptionType<FloatType>;
+    /** Bootstrap CI config (default: 200 reps, 0.95). */
     readonly bootstrap: OptionType<StructType<{
-        /** Number of bootstrap replicates */
+        /** Number of bootstrap replicates (default 200) */
         readonly reps: IntegerType;
         /** Column whose values identify clusters to resample (default: resample rows) */
         readonly cluster_column: OptionType<StringType>;
         /** Confidence level for the percentile interval (default 0.95) */
         readonly confidence_level: OptionType<FloatType>;
     }>>;
-    /** Random seed for propensity fitting and bootstrap resampling */
+    /** Random seed. */
     readonly random_state: OptionType<IntegerType>;
-}>, VariantType<{
-    /** Replace treatment with a permuted placebo - effect should vanish */
-    readonly placebo_treatment: StructType<{
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /** Add an independent random common cause - effect should be unchanged */
-    readonly random_common_cause: StructType<{
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /** Re-estimate on random data subsets - effect should be stable */
-    readonly data_subset: StructType<{
-        /** Fraction of rows kept per simulation (default 0.8) */
-        readonly subset_fraction: OptionType<FloatType>;
-        /** Number of simulations (default 100) */
-        readonly num_simulations: OptionType<IntegerType>;
-    }>;
-    /**
-     * Simulate an unobserved confounder at each given strength - a
-     * sensitivity/tipping curve. Strength acts on both treatment
-     * (flip probability for binary treatment, linear coefficient otherwise)
-     * and outcome (linear coefficient).
-     */
-    readonly unobserved_common_cause: StructType<{
-        /** Confounder effect strengths to simulate, one new effect per entry */
-        readonly effect_strengths: ArrayType<FloatType>;
+}>, StructType<{
+    /** The raw (unadjusted) mean difference — always computable. */
+    readonly naive: FloatType;
+    readonly naive_ci: OptionType<StructType<{
+        readonly lower: FloatType;
+        readonly upper: FloatType;
+    }>>;
+    /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+    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;
+    /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+    readonly balance: ArrayType<StructType<{
+        readonly column: StringType;
+        /** 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;
+        /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+        readonly std_diff: FloatType;
+    }>>;
+    readonly overlap: StructType<{
+        /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+        readonly treated_propensity: VectorType<FloatType>;
+        /** Propensity histogram for the control arm. */
+        readonly control_propensity: VectorType<FloatType>;
+        /** Fraction of rows inside the treated/control common support. */
+        readonly common_support_frac: FloatType;
+        /** Whether common support clears `min_overlap`. */
+        readonly positivity_ok: BooleanType;
     }>;
-}>], StructType<{
-    /** The original estimated effect being refuted */
-    readonly estimated_effect: FloatType;
-    /**
-     * Effect under the refutation. One entry for placebo/random-common-cause/
-     * data-subset; one entry per strength for unobserved_common_cause.
-     */
-    readonly new_effects: VectorType<FloatType>;
-    /** Refutation p-value where the refuter provides one */
-    readonly p_value: OptionType<FloatType>;
-}>>;
-/**
- * Fit an EconML LinearDML estimator for heterogeneous treatment effects.
- *
- * Cross-fits nuisance models for outcome and treatment, then fits a linear
- * CATE model on the residuals.
- *
- * @param Y - Outcome vector
- * @param T - Treatment vector
- * @param X - Effect modifier matrix (CATE varies with these)
- * @param W - Additional confounders adjusted for but not modifying the effect
- * @param config - DML configuration
- * @returns Model blob for use with dmlEffect / dmlAte
- */
-export declare const causal_dml_train: import("@elaraai/east").PlatformDefinition<[VectorType<FloatType>, VectorType<FloatType>, MatrixType<FloatType>, OptionType<MatrixType<FloatType>>, StructType<{
-    /** Nuisance model for the outcome stage (default: random_forest) */
-    readonly model_y: OptionType<VariantType<{
-        /** Random forest (regressor, or classifier for a discrete treatment) */
-        readonly random_forest: StructType<{
-            /** Number of trees (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 5) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-        readonly gradient_boosting: StructType<{
-            /** Number of boosting stages (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.1) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default 3) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Linear/logistic regression */
-        readonly linear: NullType;
+    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>;
+        }>>;
     }>>;
-    /** Nuisance model for the treatment stage (default: random_forest) */
-    readonly model_t: OptionType<VariantType<{
-        /** Random forest (regressor, or classifier for a discrete treatment) */
-        readonly random_forest: StructType<{
-            /** Number of trees (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 5) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-        readonly gradient_boosting: StructType<{
-            /** Number of boosting stages (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.1) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default 3) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Linear/logistic regression */
-        readonly linear: NullType;
+    /** 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>;
     }>>;
-    /** Treat the treatment as discrete/categorical (default false) */
-    readonly discrete_treatment: OptionType<BooleanType>;
-    /** Cross-fitting folds (default 2) */
-    readonly cv_folds: OptionType<IntegerType>;
-    /** Confidence level for effect/ATE intervals (default 0.95) */
-    readonly confidence_level: OptionType<FloatType>;
-    /** Random seed */
-    readonly random_state: OptionType<IntegerType>;
-}>], VariantType<{
-    /** Fitted EconML LinearDML estimator */
-    readonly causal_dml: StructType<{
-        /** Serialized estimator (cloudpickle) */
-        readonly data: BlobType;
-        /** Number of effect-modifier (X) features */
-        readonly n_features_x: IntegerType;
-        /** Confidence level used for effect/ATE intervals */
-        readonly confidence_level: FloatType;
+    readonly verdict: VariantType<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        readonly not_estimable: StringType;
     }>;
-}>>;
-/**
- * Per-row conditional average treatment effects (CATE) from a fitted DML model.
- *
- * @param model - Fitted DML model blob
- * @param X - Effect modifier matrix
- * @returns CATE per row (outcome units per treatment unit)
- */
-export declare const causal_dml_effect: import("@elaraai/east").PlatformDefinition<[VariantType<{
-    /** Fitted EconML LinearDML estimator */
-    readonly causal_dml: StructType<{
-        /** Serialized estimator (cloudpickle) */
-        readonly data: BlobType;
-        /** Number of effect-modifier (X) features */
-        readonly n_features_x: IntegerType;
-        /** Confidence level used for effect/ATE intervals */
-        readonly confidence_level: FloatType;
+}>, 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>>;
+}>], StructType<{
+    readonly verdict: VariantType<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        readonly not_estimable: StringType;
     }>;
-}>, MatrixType<FloatType>], VectorType<FloatType>>;
-/**
- * Average treatment effect with confidence interval from a fitted DML model.
- *
- * @param model - Fitted DML model blob
- * @param X - Effect modifier matrix to average over
- * @returns ATE with interval at the confidence level configured at training
- */
-export declare const causal_dml_ate: import("@elaraai/east").PlatformDefinition<[VariantType<{
-    /** Fitted EconML LinearDML estimator */
-    readonly causal_dml: StructType<{
-        /** Serialized estimator (cloudpickle) */
-        readonly data: BlobType;
-        /** Number of effect-modifier (X) features */
-        readonly n_features_x: IntegerType;
-        /** Confidence level used for effect/ATE intervals */
-        readonly confidence_level: FloatType;
+    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;
     }>;
-}>, MatrixType<FloatType>], StructType<{
-    /** Average treatment effect over the given X */
-    readonly ate: FloatType;
-    /** Lower bound at the model's confidence level */
-    readonly lower: FloatType;
-    /** Upper bound at the model's confidence level */
-    readonly upper: FloatType;
-}>>;
-/**
- * Accumulated local effects dose-response curve of a feature on an outcome.
- *
- * Fits a gradient boosting emulator on all non-outcome columns, then
- * computes the ALE curve of the feature - robust to correlated features,
- * unlike partial dependence.
- *
- * @param data - Data matrix (rows = units, columns named by config.columns)
- * @param config - ALE configuration
- * @returns ALE curve with grid, centered effect, optional CI, and bin sizes
- */
-export declare const causal_ale: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-    /** Column names for the data matrix (one per column, in order) */
-    readonly columns: ArrayType<StringType>;
-    /** Outcome column the emulator predicts */
-    readonly outcome: StringType;
-    /** Continuous feature column to compute the ALE curve for */
-    readonly feature: StringType;
-    /** Columns holding integer category codes, one-hot encoded internally */
-    readonly categorical: OptionType<ArrayType<StringType>>;
-    /** Number of grid intervals (default 10) */
-    readonly grid_size: OptionType<IntegerType>;
-    /** Include confidence intervals (default true) */
-    readonly include_ci: OptionType<BooleanType>;
-    /** Confidence level for the CI (default 0.95) */
-    readonly confidence_level: OptionType<FloatType>;
-    /** Emulator (HistGradientBoosting) hyperparameters */
-    readonly emulator: OptionType<StructType<{
-        /** Number of boosting iterations (default 300) */
-        readonly n_estimators: OptionType<IntegerType>;
-        /** Learning rate (default 0.05) */
-        readonly learning_rate: OptionType<FloatType>;
-        /** Maximum tree depth (default unlimited) */
-        readonly max_depth: OptionType<IntegerType>;
-        /** Minimum samples per leaf (default 20; lower for small datasets) */
-        readonly min_samples_leaf: OptionType<IntegerType>;
+    /** 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`; `none` when there's no comparison group. */
+    readonly current_power: OptionType<FloatType>;
+    /** Categories both groups must be matched on (most-imbalanced confounders). */
+    readonly match_on: ArrayType<StringType>;
+    /** Ranked split options (even split first; cost-saving alternates). */
+    readonly options: ArrayType<StructType<{
+        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;
     }>>;
-    /** Random seed for the emulator */
-    readonly random_state: OptionType<IntegerType>;
-}>], StructType<{
-    /** Feature grid values (interval edges) */
-    readonly grid: VectorType<FloatType>;
-    /** Centered ALE effect at each grid value (outcome units) */
-    readonly effect: VectorType<FloatType>;
-    /** Lower CI at each grid value (present when include_ci) */
-    readonly lower: OptionType<VectorType<FloatType>>;
-    /** Upper CI at each grid value (present when include_ci) */
-    readonly upper: OptionType<VectorType<FloatType>>;
-    /** Number of samples in each grid interval */
-    readonly size: VectorType<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 definitions for causal inference functions.
- */
+/** Type definitions for causal inference. */
 export declare const CausalTypes: {
     readonly CausalWeightingSchemeType: VariantType<{
         /** Raw inverse propensity weights */
@@ -766,7 +794,7 @@ export declare const CausalTypes: {
         readonly ips_normalized_weight: NullType;
     }>;
     readonly CausalEstimatorType: VariantType<{
-        /** Linear regression of outcome on treatment + common causes */
+        /** Linear regression of outcome on treatment + common causes (default) */
         readonly linear_regression: NullType;
         /** Inverse propensity score weighting (binary treatment only) */
         readonly propensity_score_weighting: StructType<{
@@ -789,39 +817,40 @@ export declare const CausalTypes: {
         /** Average treatment effect on the controls */
         readonly atc: NullType;
     }>;
-    readonly PropensityTrimType: VariantType<{
-        /** Keep units inside the common-support overlap of treated and control propensities */
-        readonly overlap: NullType;
-        /** Keep units with propensity inside explicit bounds */
-        readonly bounds: StructType<{
-            /** Minimum propensity score to keep */
-            readonly lower: FloatType;
-            /** Maximum propensity score to keep */
-            readonly upper: FloatType;
-        }>;
-    }>;
     readonly CausalBootstrapConfigType: StructType<{
-        /** Number of bootstrap replicates */
+        /** Number of bootstrap replicates (default 200) */
         readonly reps: IntegerType;
         /** Column whose values identify clusters to resample (default: resample rows) */
         readonly cluster_column: OptionType<StringType>;
         /** Confidence level for the percentile interval (default 0.95) */
         readonly confidence_level: OptionType<FloatType>;
     }>;
-    readonly CausalEffectConfigType: StructType<{
-        /** Column names for the data matrix (one per column, in order) */
-        readonly columns: ArrayType<StringType>;
-        /** Treatment column (must be 0/1 for propensity score weighting) */
+    readonly CiType: StructType<{
+        readonly lower: FloatType;
+        readonly upper: FloatType;
+    }>;
+    readonly 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>>;
+    }>;
+    readonly CausalExperimentConfigType: StructType<{
+        /** Binary (0/1) treatment column. */
         readonly treatment: StringType;
-        /** Outcome column */
+        /** Outcome column. */
         readonly outcome: StringType;
-        /** Confounder columns to adjust for (the backdoor set) */
+        /** Confounders to adjust for (the backdoor set). */
         readonly common_causes: ArrayType<StringType>;
-        /** Columns holding integer category codes, one-hot encoded internally */
+        /** Confounder columns holding categories (string or int codes), one-hot encoded. */
         readonly categorical: OptionType<ArrayType<StringType>>;
-        /** Effect estimator (default: linear_regression) */
+        /** Estimator (default: linear_regression). */
         readonly method: OptionType<VariantType<{
-            /** Linear regression of outcome on treatment + common causes */
+            /** Linear regression of outcome on treatment + common causes (default) */
             readonly linear_regression: NullType;
             /** Inverse propensity score weighting (binary treatment only) */
             readonly propensity_score_weighting: StructType<{
@@ -836,8 +865,8 @@ export declare const CausalTypes: {
                 }>>;
             }>;
         }>>;
-        /** Target population (default: ate) */
-        readonly target_units: OptionType<VariantType<{
+        /** Target population (default: ate). */
+        readonly estimand: OptionType<VariantType<{
             /** Average treatment effect over all units */
             readonly ate: NullType;
             /** Average treatment effect on the treated */
@@ -845,313 +874,306 @@ export declare const CausalTypes: {
             /** Average treatment effect on the controls */
             readonly atc: NullType;
         }>>;
-        /** Propensity trimming applied before estimation (psw only) */
-        readonly trim: OptionType<VariantType<{
-            /** Keep units inside the common-support overlap of treated and control propensities */
-            readonly overlap: NullType;
-            /** Keep units with propensity inside explicit bounds */
-            readonly bounds: StructType<{
-                /** Minimum propensity score to keep */
-                readonly lower: FloatType;
-                /** Maximum propensity score to keep */
-                readonly upper: FloatType;
-            }>;
+        /** Which robustness checks to run. */
+        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>>;
         }>>;
-        /** Bootstrap confidence interval (omit to skip CI computation) */
+        /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+        readonly dose_feature: OptionType<StringType>;
+        /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+        readonly min_overlap: OptionType<FloatType>;
+        /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+        readonly min_treatment_variation: OptionType<FloatType>;
+        /** Bootstrap CI config (default: 200 reps, 0.95). */
         readonly bootstrap: OptionType<StructType<{
-            /** Number of bootstrap replicates */
+            /** Number of bootstrap replicates (default 200) */
             readonly reps: IntegerType;
             /** Column whose values identify clusters to resample (default: resample rows) */
             readonly cluster_column: OptionType<StringType>;
             /** Confidence level for the percentile interval (default 0.95) */
             readonly confidence_level: OptionType<FloatType>;
         }>>;
-        /** Random seed for propensity fitting and bootstrap resampling */
+        /** Random seed. */
         readonly random_state: OptionType<IntegerType>;
     }>;
-    readonly CausalRefuterType: VariantType<{
-        /** Replace treatment with a permuted placebo - effect should vanish */
-        readonly placebo_treatment: StructType<{
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /** Add an independent random common cause - effect should be unchanged */
-        readonly random_common_cause: StructType<{
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /** Re-estimate on random data subsets - effect should be stable */
-        readonly data_subset: StructType<{
-            /** Fraction of rows kept per simulation (default 0.8) */
-            readonly subset_fraction: OptionType<FloatType>;
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /**
-         * Simulate an unobserved confounder at each given strength - a
-         * sensitivity/tipping curve. Strength acts on both treatment
-         * (flip probability for binary treatment, linear coefficient otherwise)
-         * and outcome (linear coefficient).
-         */
-        readonly unobserved_common_cause: StructType<{
-            /** Confounder effect strengths to simulate, one new effect per entry */
-            readonly effect_strengths: ArrayType<FloatType>;
-        }>;
+    readonly BalanceRowType: StructType<{
+        readonly column: StringType;
+        /** 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;
+        /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+        readonly std_diff: FloatType;
     }>;
-    readonly CausalNuisanceModelType: VariantType<{
-        /** Random forest (regressor, or classifier for a discrete treatment) */
-        readonly random_forest: StructType<{
-            /** Number of trees (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 5) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-        readonly gradient_boosting: StructType<{
-            /** Number of boosting stages (default 100) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.1) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default 3) */
-            readonly max_depth: OptionType<IntegerType>;
-        }>;
-        /** Linear/logistic regression */
-        readonly linear: NullType;
+    readonly OverlapDiagnosticType: StructType<{
+        /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+        readonly treated_propensity: VectorType<FloatType>;
+        /** Propensity histogram for the control arm. */
+        readonly control_propensity: VectorType<FloatType>;
+        /** Fraction of rows inside the treated/control common support. */
+        readonly common_support_frac: FloatType;
+        /** Whether common support clears `min_overlap`. */
+        readonly positivity_ok: BooleanType;
     }>;
-    readonly CausalDMLConfigType: StructType<{
-        /** Nuisance model for the outcome stage (default: random_forest) */
-        readonly model_y: OptionType<VariantType<{
-            /** Random forest (regressor, or classifier for a discrete treatment) */
-            readonly random_forest: StructType<{
-                /** Number of trees (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 5) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-            readonly gradient_boosting: StructType<{
-                /** Number of boosting stages (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.1) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default 3) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Linear/logistic regression */
-            readonly linear: NullType;
-        }>>;
-        /** Nuisance model for the treatment stage (default: random_forest) */
-        readonly model_t: OptionType<VariantType<{
-            /** Random forest (regressor, or classifier for a discrete treatment) */
-            readonly random_forest: StructType<{
-                /** Number of trees (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 5) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-            readonly gradient_boosting: StructType<{
-                /** Number of boosting stages (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.1) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default 3) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Linear/logistic regression */
-            readonly linear: NullType;
+    readonly 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>;
         }>>;
-        /** Treat the treatment as discrete/categorical (default false) */
-        readonly discrete_treatment: OptionType<BooleanType>;
-        /** Cross-fitting folds (default 2) */
-        readonly cv_folds: OptionType<IntegerType>;
-        /** Confidence level for effect/ATE intervals (default 0.95) */
-        readonly confidence_level: OptionType<FloatType>;
-        /** Random seed */
-        readonly random_state: OptionType<IntegerType>;
     }>;
-    readonly CausalALEConfigType: StructType<{
-        /** Column names for the data matrix (one per column, in order) */
-        readonly columns: ArrayType<StringType>;
-        /** Outcome column the emulator predicts */
-        readonly outcome: StringType;
-        /** Continuous feature column to compute the ALE curve for */
+    readonly DoseResponseType: StructType<{
         readonly feature: StringType;
-        /** Columns holding integer category codes, one-hot encoded internally */
-        readonly categorical: OptionType<ArrayType<StringType>>;
-        /** Number of grid intervals (default 10) */
-        readonly grid_size: OptionType<IntegerType>;
-        /** Include confidence intervals (default true) */
-        readonly include_ci: OptionType<BooleanType>;
-        /** Confidence level for the CI (default 0.95) */
-        readonly confidence_level: OptionType<FloatType>;
-        /** Emulator (HistGradientBoosting) hyperparameters */
-        readonly emulator: OptionType<StructType<{
-            /** Number of boosting iterations (default 300) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.05) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 20; lower for small datasets) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
-        }>>;
-        /** Random seed for the emulator */
-        readonly random_state: OptionType<IntegerType>;
+        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 CausalDMLModelBlobType: VariantType<{
-        /** Fitted EconML LinearDML estimator */
-        readonly causal_dml: StructType<{
-            /** Serialized estimator (cloudpickle) */
-            readonly data: BlobType;
-            /** Number of effect-modifier (X) features */
-            readonly n_features_x: IntegerType;
-            /** Confidence level used for effect/ATE intervals */
-            readonly confidence_level: FloatType;
-        }>;
+    readonly ExperimentVerdictType: VariantType<{
+        /** A real, robust, material effect. */
+        readonly causal: NullType;
+        /** A small but real effect, or no clear effect after adjustment. */
+        readonly modest: NullType;
+        /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+        readonly adjustment_insufficient: NullType;
+        /** No like-for-like comparison exists (positivity violated). */
+        readonly non_identifiable_positivity: NullType;
+        /** The estimand can't be formed (treatment barely varies). */
+        readonly not_estimable: StringType;
     }>;
-    readonly CausalEffectResultType: StructType<{
-        /** Point estimate of the effect (outcome units per treatment unit) */
-        readonly effect: FloatType;
-        /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-        readonly ci: OptionType<StructType<{
-            /** Lower bound */
+    readonly CausalExperimentResultType: StructType<{
+        /** The raw (unadjusted) mean difference — always computable. */
+        readonly naive: FloatType;
+        readonly naive_ci: OptionType<StructType<{
             readonly lower: FloatType;
-            /** Upper bound */
             readonly upper: FloatType;
         }>>;
-        /** Rows used for estimation (after trimming) */
-        readonly n_samples: IntegerType;
-        /** Treated rows used */
+        /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+        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;
-        /** Control rows used */
         readonly n_control: IntegerType;
+        readonly n_dropped: IntegerType;
+        /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+        readonly balance: ArrayType<StructType<{
+            readonly column: StringType;
+            /** 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;
+            /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+            readonly std_diff: FloatType;
+        }>>;
+        readonly overlap: StructType<{
+            /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+            readonly treated_propensity: VectorType<FloatType>;
+            /** Propensity histogram for the control arm. */
+            readonly control_propensity: VectorType<FloatType>;
+            /** Fraction of rows inside the treated/control common support. */
+            readonly common_support_frac: FloatType;
+            /** Whether common support clears `min_overlap`. */
+            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<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            readonly not_estimable: StringType;
+        }>;
     }>;
-    readonly CausalRefuteResultType: StructType<{
-        /** The original estimated effect being refuted */
-        readonly estimated_effect: FloatType;
-        /**
-         * Effect under the refutation. One entry for placebo/random-common-cause/
-         * data-subset; one entry per strength for unobserved_common_cause.
-         */
-        readonly new_effects: VectorType<FloatType>;
-        /** Refutation p-value where the refuter provides one */
-        readonly p_value: OptionType<FloatType>;
+    readonly 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;
     }>;
-    readonly CausalATEResultType: StructType<{
-        /** Average treatment effect over the given X */
-        readonly ate: FloatType;
-        /** Lower bound at the model's confidence level */
-        readonly lower: FloatType;
-        /** Upper bound at the model's confidence level */
-        readonly upper: FloatType;
+    readonly TrialOptionType: StructType<{
+        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;
     }>;
-    readonly ALEResultType: StructType<{
-        /** Feature grid values (interval edges) */
-        readonly grid: VectorType<FloatType>;
-        /** Centered ALE effect at each grid value (outcome units) */
-        readonly effect: VectorType<FloatType>;
-        /** Lower CI at each grid value (present when include_ci) */
-        readonly lower: OptionType<VectorType<FloatType>>;
-        /** Upper CI at each grid value (present when include_ci) */
-        readonly upper: OptionType<VectorType<FloatType>>;
-        /** Number of samples in each grid interval */
-        readonly size: VectorType<IntegerType>;
+    readonly PowerCurveType: StructType<{
+        readonly n: VectorType<IntegerType>;
+        readonly power: VectorType<FloatType>;
+    }>;
+    readonly ExperimentDesignType: StructType<{
+        readonly verdict: VariantType<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            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;
+        }>;
+        /** 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`; `none` when there's no comparison group. */
+        readonly current_power: OptionType<FloatType>;
+        /** Categories both groups must be matched on (most-imbalanced confounders). */
+        readonly match_on: ArrayType<StringType>;
+        /** Ranked split options (even split first; cost-saving alternates). */
+        readonly options: ArrayType<StructType<{
+            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;
+    }>;
+    readonly 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>>;
     }>;
 };
 /**
- * Causal inference.
+ * Causal inference — one declarative entry point.
  *
- * Backdoor-adjusted effect estimation and refutation (DoWhy),
- * heterogeneous treatment effects via double machine learning
- * (EconML LinearDML), and accumulated local effects dose-response
- * curves (PyALE).
+ * `Causal.experiment(data, config)` runs a complete, honest causal experiment
+ * for a binary treatment and returns the naive vs adjusted effect, confounder
+ * balance, propensity overlap, a robustness check, and a verdict
+ * (`causal` / `modest` / `adjustment_insufficient` / `non_identifiable_positivity`
+ * / `not_estimable`). It refuses (`adjusted = none`) when the data can't support
+ * an estimate. DoWhy / EconML / PyALE are internal implementation it composes.
  *
  * @example
  * ```ts
- * import { East, FloatType, variant } from "@elaraai/east";
- * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
+ * import { East, ArrayType, StructType, FloatType, BooleanType, variant } from "@elaraai/east";
+ * import { Causal } from "@elaraai/east-py-datascience";
  *
- * const estimate = East.function(
- *     [MatrixType(FloatType)],
- *     Causal.Types.CausalEffectResultType,
- *     ($, data) => {
- *         const config = $.let({
- *             columns: ["treated", "outcome", "confounder"],
- *             treatment: "treated",
- *             outcome: "outcome",
- *             common_causes: ["confounder"],
- *             categorical: variant('none', null),
- *             method: variant('some', variant('linear_regression', null)),
- *             target_units: variant('some', variant('ate', null)),
- *             trim: variant('none', null),
- *             bootstrap: variant('none', null),
- *             random_state: variant('some', 42n),
- *         }, Causal.Types.CausalEffectConfigType);
- *         return $.return(Causal.effect(data, config));
- *     }
- * );
+ * const Row = StructType({ treated: BooleanType, outcome: FloatType, z: FloatType });
+ * const run = East.function([ArrayType(Row)], Causal.Types.CausalExperimentResultType, ($, data) => {
+ *   const config = $.let({
+ *     treatment: "treated", outcome: "outcome", common_causes: ["z"],
+ *     categorical: variant('none', null),
+ *     method: variant('none', null), estimand: variant('none', null),
+ *     refute: variant('some', { placebo: true, random_common_cause: false }),
+ *     min_overlap: variant('some', 0.1), min_treatment_variation: variant('some', 0.02),
+ *     bootstrap: variant('none', null), random_state: variant('some', 42n),
+ *   }, Causal.Types.CausalExperimentConfigType);
+ *   return $.return(Causal.experiment([Row], data, config));
+ * });
  * ```
  */
 export declare const Causal: {
-    /**
-     * Estimate a backdoor-adjusted causal effect of treatment on outcome.
-     *
-     * Linear regression or inverse propensity score weighting (with
-     * optional propensity trimming), plus optional cluster bootstrap CI.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalEffectConfigType, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const attEstimate = East.function(
-     *     [MatrixType(FloatType)],
-     *     Causal.Types.CausalEffectResultType,
-     *     ($, data) => {
-     *         const config = $.let({
-     *             columns: ["treated", "outcome", "z1", "z2", "batch"],
-     *             treatment: "treated",
-     *             outcome: "outcome",
-     *             common_causes: ["z1", "z2"],
-     *             categorical: variant('none', null),
-     *             method: variant('some', variant('propensity_score_weighting', {
-     *                 weighting_scheme: variant('some', variant('ips_stabilized_weight', null)),
-     *             })),
-     *             target_units: variant('some', variant('att', null)),
-     *             trim: variant('some', variant('overlap', null)),
-     *             bootstrap: variant('some', {
-     *                 reps: 200n,
-     *                 cluster_column: variant('some', "batch"),
-     *                 confidence_level: variant('some', 0.95),
-     *             }),
-     *             random_state: variant('some', 42n),
-     *         }, CausalEffectConfigType);
-     *         return $.return(Causal.effect(data, config));
-     *     }
-     * );
-     * ```
-     */
-    readonly effect: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-        /** Column names for the data matrix (one per column, in order) */
-        readonly columns: ArrayType<StringType>;
-        /** Treatment column (must be 0/1 for propensity score weighting) */
+    readonly experiment: import("@elaraai/east").GenericPlatformDefinition<readonly ["T"], readonly [ArrayType<unknown>, StructType<{
+        /** Binary (0/1) treatment column. */
         readonly treatment: StringType;
-        /** Outcome column */
+        /** Outcome column. */
         readonly outcome: StringType;
-        /** Confounder columns to adjust for (the backdoor set) */
+        /** Confounders to adjust for (the backdoor set). */
         readonly common_causes: ArrayType<StringType>;
-        /** Columns holding integer category codes, one-hot encoded internally */
+        /** Confounder columns holding categories (string or int codes), one-hot encoded. */
         readonly categorical: OptionType<ArrayType<StringType>>;
-        /** Effect estimator (default: linear_regression) */
+        /** Estimator (default: linear_regression). */
         readonly method: OptionType<VariantType<{
-            /** Linear regression of outcome on treatment + common causes */
+            /** Linear regression of outcome on treatment + common causes (default) */
             readonly linear_regression: NullType;
             /** Inverse propensity score weighting (binary treatment only) */
             readonly propensity_score_weighting: StructType<{
@@ -1166,8 +1188,8 @@ export declare const Causal: {
                 }>>;
             }>;
         }>>;
-        /** Target population (default: ate) */
-        readonly target_units: OptionType<VariantType<{
+        /** Target population (default: ate). */
+        readonly estimand: OptionType<VariantType<{
             /** Average treatment effect over all units */
             readonly ate: NullType;
             /** Average treatment effect on the treated */
@@ -1175,82 +1197,129 @@ export declare const Causal: {
             /** Average treatment effect on the controls */
             readonly atc: NullType;
         }>>;
-        /** Propensity trimming applied before estimation (psw only) */
-        readonly trim: OptionType<VariantType<{
-            /** Keep units inside the common-support overlap of treated and control propensities */
-            readonly overlap: NullType;
-            /** Keep units with propensity inside explicit bounds */
-            readonly bounds: StructType<{
-                /** Minimum propensity score to keep */
-                readonly lower: FloatType;
-                /** Maximum propensity score to keep */
-                readonly upper: FloatType;
-            }>;
+        /** Which robustness checks to run. */
+        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>>;
         }>>;
-        /** Bootstrap confidence interval (omit to skip CI computation) */
+        /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+        readonly dose_feature: OptionType<StringType>;
+        /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+        readonly min_overlap: OptionType<FloatType>;
+        /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+        readonly min_treatment_variation: OptionType<FloatType>;
+        /** Bootstrap CI config (default: 200 reps, 0.95). */
         readonly bootstrap: OptionType<StructType<{
-            /** Number of bootstrap replicates */
+            /** Number of bootstrap replicates (default 200) */
             readonly reps: IntegerType;
             /** Column whose values identify clusters to resample (default: resample rows) */
             readonly cluster_column: OptionType<StringType>;
             /** Confidence level for the percentile interval (default 0.95) */
             readonly confidence_level: OptionType<FloatType>;
         }>>;
-        /** Random seed for propensity fitting and bootstrap resampling */
+        /** Random seed. */
         readonly random_state: OptionType<IntegerType>;
     }>], StructType<{
-        /** Point estimate of the effect (outcome units per treatment unit) */
-        readonly effect: FloatType;
-        /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-        readonly ci: OptionType<StructType<{
-            /** Lower bound */
+        /** The raw (unadjusted) mean difference — always computable. */
+        readonly naive: FloatType;
+        readonly naive_ci: OptionType<StructType<{
             readonly lower: FloatType;
-            /** Upper bound */
             readonly upper: FloatType;
         }>>;
-        /** Rows used for estimation (after trimming) */
-        readonly n_samples: IntegerType;
-        /** Treated rows used */
+        /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+        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;
-        /** Control rows used */
         readonly n_control: IntegerType;
+        readonly n_dropped: IntegerType;
+        /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+        readonly balance: ArrayType<StructType<{
+            readonly column: StringType;
+            /** 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;
+            /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+            readonly std_diff: FloatType;
+        }>>;
+        readonly overlap: StructType<{
+            /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+            readonly treated_propensity: VectorType<FloatType>;
+            /** Propensity histogram for the control arm. */
+            readonly control_propensity: VectorType<FloatType>;
+            /** Fraction of rows inside the treated/control common support. */
+            readonly common_support_frac: FloatType;
+            /** Whether common support clears `min_overlap`. */
+            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<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            readonly not_estimable: StringType;
+        }>;
     }>>;
-    /**
-     * Refute an estimated causal effect with placebo, random common cause,
-     * data subset, or unobserved-confounder sensitivity tests.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const placebo = East.function(
-     *     [MatrixType(FloatType), Causal.Types.CausalEffectConfigType],
-     *     Causal.Types.CausalRefuteResultType,
-     *     ($, data, config) => {
-     *         const refuter = $.let(variant('placebo_treatment', {
-     *             num_simulations: variant('some', 50n),
-     *         }), Causal.Types.CausalRefuterType);
-     *         // new_effects should be near zero if the estimate is causal
-     *         return $.return(Causal.refute(data, config, refuter));
-     *     }
-     * );
-     * ```
-     */
-    readonly refute: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-        /** Column names for the data matrix (one per column, in order) */
-        readonly columns: ArrayType<StringType>;
-        /** Treatment column (must be 0/1 for propensity score weighting) */
+    /** Design the real controlled trial that would validate an experiment result. */
+    readonly designValidation: import("@elaraai/east").GenericPlatformDefinition<readonly ["T"], readonly [ArrayType<unknown>, StructType<{
+        /** Binary (0/1) treatment column. */
         readonly treatment: StringType;
-        /** Outcome column */
+        /** Outcome column. */
         readonly outcome: StringType;
-        /** Confounder columns to adjust for (the backdoor set) */
+        /** Confounders to adjust for (the backdoor set). */
         readonly common_causes: ArrayType<StringType>;
-        /** Columns holding integer category codes, one-hot encoded internally */
+        /** Confounder columns holding categories (string or int codes), one-hot encoded. */
         readonly categorical: OptionType<ArrayType<StringType>>;
-        /** Effect estimator (default: linear_regression) */
+        /** Estimator (default: linear_regression). */
         readonly method: OptionType<VariantType<{
-            /** Linear regression of outcome on treatment + common causes */
+            /** Linear regression of outcome on treatment + common causes (default) */
             readonly linear_regression: NullType;
             /** Inverse propensity score weighting (binary treatment only) */
             readonly propensity_score_weighting: StructType<{
@@ -1265,8 +1334,8 @@ export declare const Causal: {
                 }>>;
             }>;
         }>>;
-        /** Target population (default: ate) */
-        readonly target_units: OptionType<VariantType<{
+        /** Target population (default: ate). */
+        readonly estimand: OptionType<VariantType<{
             /** Average treatment effect over all units */
             readonly ate: NullType;
             /** Average treatment effect on the treated */
@@ -1274,289 +1343,175 @@ export declare const Causal: {
             /** Average treatment effect on the controls */
             readonly atc: NullType;
         }>>;
-        /** Propensity trimming applied before estimation (psw only) */
-        readonly trim: OptionType<VariantType<{
-            /** Keep units inside the common-support overlap of treated and control propensities */
-            readonly overlap: NullType;
-            /** Keep units with propensity inside explicit bounds */
-            readonly bounds: StructType<{
-                /** Minimum propensity score to keep */
-                readonly lower: FloatType;
-                /** Maximum propensity score to keep */
-                readonly upper: FloatType;
-            }>;
+        /** Which robustness checks to run. */
+        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>>;
         }>>;
-        /** Bootstrap confidence interval (omit to skip CI computation) */
+        /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+        readonly dose_feature: OptionType<StringType>;
+        /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+        readonly min_overlap: OptionType<FloatType>;
+        /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+        readonly min_treatment_variation: OptionType<FloatType>;
+        /** Bootstrap CI config (default: 200 reps, 0.95). */
         readonly bootstrap: OptionType<StructType<{
-            /** Number of bootstrap replicates */
+            /** Number of bootstrap replicates (default 200) */
             readonly reps: IntegerType;
             /** Column whose values identify clusters to resample (default: resample rows) */
             readonly cluster_column: OptionType<StringType>;
             /** Confidence level for the percentile interval (default 0.95) */
             readonly confidence_level: OptionType<FloatType>;
         }>>;
-        /** Random seed for propensity fitting and bootstrap resampling */
+        /** Random seed. */
         readonly random_state: OptionType<IntegerType>;
-    }>, VariantType<{
-        /** Replace treatment with a permuted placebo - effect should vanish */
-        readonly placebo_treatment: StructType<{
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /** Add an independent random common cause - effect should be unchanged */
-        readonly random_common_cause: StructType<{
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /** Re-estimate on random data subsets - effect should be stable */
-        readonly data_subset: StructType<{
-            /** Fraction of rows kept per simulation (default 0.8) */
-            readonly subset_fraction: OptionType<FloatType>;
-            /** Number of simulations (default 100) */
-            readonly num_simulations: OptionType<IntegerType>;
-        }>;
-        /**
-         * Simulate an unobserved confounder at each given strength - a
-         * sensitivity/tipping curve. Strength acts on both treatment
-         * (flip probability for binary treatment, linear coefficient otherwise)
-         * and outcome (linear coefficient).
-         */
-        readonly unobserved_common_cause: StructType<{
-            /** Confounder effect strengths to simulate, one new effect per entry */
-            readonly effect_strengths: ArrayType<FloatType>;
+    }>, StructType<{
+        /** The raw (unadjusted) mean difference — always computable. */
+        readonly naive: FloatType;
+        readonly naive_ci: OptionType<StructType<{
+            readonly lower: FloatType;
+            readonly upper: FloatType;
+        }>>;
+        /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+        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;
+        /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+        readonly balance: ArrayType<StructType<{
+            readonly column: StringType;
+            /** 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;
+            /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+            readonly std_diff: FloatType;
+        }>>;
+        readonly overlap: StructType<{
+            /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+            readonly treated_propensity: VectorType<FloatType>;
+            /** Propensity histogram for the control arm. */
+            readonly control_propensity: VectorType<FloatType>;
+            /** Fraction of rows inside the treated/control common support. */
+            readonly common_support_frac: FloatType;
+            /** Whether common support clears `min_overlap`. */
+            readonly positivity_ok: BooleanType;
         }>;
-    }>], StructType<{
-        /** The original estimated effect being refuted */
-        readonly estimated_effect: FloatType;
-        /**
-         * Effect under the refutation. One entry for placebo/random-common-cause/
-         * data-subset; one entry per strength for unobserved_common_cause.
-         */
-        readonly new_effects: VectorType<FloatType>;
-        /** Refutation p-value where the refuter provides one */
-        readonly p_value: OptionType<FloatType>;
-    }>>;
-    /**
-     * Fit an EconML LinearDML estimator for heterogeneous treatment effects.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalDMLConfigType, MatrixType, VectorType } from "@elaraai/east-py-datascience";
-     *
-     * const train = East.function(
-     *     [VectorType(FloatType), VectorType(FloatType), MatrixType(FloatType), MatrixType(FloatType)],
-     *     Causal.Types.CausalDMLModelBlobType,
-     *     ($, Y, T, X, W) => {
-     *         const config = $.let({
-     *             model_y: variant('some', variant('random_forest', {
-     *                 n_estimators: variant('some', 100n),
-     *                 min_samples_leaf: variant('some', 5n),
-     *                 max_depth: variant('none', null),
-     *             })),
-     *             model_t: variant('none', null),
-     *             discrete_treatment: variant('none', null),
-     *             cv_folds: variant('some', 2n),
-     *             confidence_level: variant('some', 0.95),
-     *             random_state: variant('some', 42n),
-     *         }, CausalDMLConfigType);
-     *         return $.return(Causal.dmlTrain(Y, T, X, variant('some', W), config));
-     *     }
-     * );
-     * ```
-     */
-    readonly dmlTrain: import("@elaraai/east").PlatformDefinition<[VectorType<FloatType>, VectorType<FloatType>, MatrixType<FloatType>, OptionType<MatrixType<FloatType>>, StructType<{
-        /** Nuisance model for the outcome stage (default: random_forest) */
-        readonly model_y: OptionType<VariantType<{
-            /** Random forest (regressor, or classifier for a discrete treatment) */
-            readonly random_forest: StructType<{
-                /** Number of trees (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 5) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-            readonly gradient_boosting: StructType<{
-                /** Number of boosting stages (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.1) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default 3) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Linear/logistic regression */
-            readonly linear: NullType;
+        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>;
+            }>>;
         }>>;
-        /** Nuisance model for the treatment stage (default: random_forest) */
-        readonly model_t: OptionType<VariantType<{
-            /** Random forest (regressor, or classifier for a discrete treatment) */
-            readonly random_forest: StructType<{
-                /** Number of trees (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 5) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-            readonly gradient_boosting: StructType<{
-                /** Number of boosting stages (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.1) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default 3) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Linear/logistic regression */
-            readonly linear: NullType;
+        /** 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>;
         }>>;
-        /** Treat the treatment as discrete/categorical (default false) */
-        readonly discrete_treatment: OptionType<BooleanType>;
-        /** Cross-fitting folds (default 2) */
-        readonly cv_folds: OptionType<IntegerType>;
-        /** Confidence level for effect/ATE intervals (default 0.95) */
-        readonly confidence_level: OptionType<FloatType>;
-        /** Random seed */
-        readonly random_state: OptionType<IntegerType>;
-    }>], VariantType<{
-        /** Fitted EconML LinearDML estimator */
-        readonly causal_dml: StructType<{
-            /** Serialized estimator (cloudpickle) */
-            readonly data: BlobType;
-            /** Number of effect-modifier (X) features */
-            readonly n_features_x: IntegerType;
-            /** Confidence level used for effect/ATE intervals */
-            readonly confidence_level: FloatType;
+        readonly verdict: VariantType<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            readonly not_estimable: StringType;
         }>;
-    }>>;
-    /**
-     * Per-row conditional average treatment effects from a fitted DML model.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType } from "@elaraai/east";
-     * import { Causal, MatrixType, VectorType } from "@elaraai/east-py-datascience";
-     *
-     * const cate = East.function(
-     *     [Causal.Types.CausalDMLModelBlobType, MatrixType(FloatType)],
-     *     VectorType(FloatType),
-     *     ($, model, X) => $.return(Causal.dmlEffect(model, X))
-     * );
-     * ```
-     */
-    readonly dmlEffect: import("@elaraai/east").PlatformDefinition<[VariantType<{
-        /** Fitted EconML LinearDML estimator */
-        readonly causal_dml: StructType<{
-            /** Serialized estimator (cloudpickle) */
-            readonly data: BlobType;
-            /** Number of effect-modifier (X) features */
-            readonly n_features_x: IntegerType;
-            /** Confidence level used for effect/ATE intervals */
-            readonly confidence_level: FloatType;
+    }>, 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>>;
+    }>], StructType<{
+        readonly verdict: VariantType<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            readonly not_estimable: StringType;
         }>;
-    }>, MatrixType<FloatType>], VectorType<FloatType>>;
-    /**
-     * Average treatment effect with confidence interval from a fitted DML model.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType } from "@elaraai/east";
-     * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const ate = East.function(
-     *     [Causal.Types.CausalDMLModelBlobType, MatrixType(FloatType)],
-     *     Causal.Types.CausalATEResultType,
-     *     ($, model, X) => $.return(Causal.dmlAte(model, X))
-     * );
-     * ```
-     */
-    readonly dmlAte: import("@elaraai/east").PlatformDefinition<[VariantType<{
-        /** Fitted EconML LinearDML estimator */
-        readonly causal_dml: StructType<{
-            /** Serialized estimator (cloudpickle) */
-            readonly data: BlobType;
-            /** Number of effect-modifier (X) features */
-            readonly n_features_x: IntegerType;
-            /** Confidence level used for effect/ATE intervals */
-            readonly confidence_level: FloatType;
+        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;
         }>;
-    }>, MatrixType<FloatType>], StructType<{
-        /** Average treatment effect over the given X */
-        readonly ate: FloatType;
-        /** Lower bound at the model's confidence level */
-        readonly lower: FloatType;
-        /** Upper bound at the model's confidence level */
-        readonly upper: FloatType;
-    }>>;
-    /**
-     * Accumulated local effects dose-response curve of a feature on an outcome.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalALEConfigType, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const doseResponse = East.function(
-     *     [MatrixType(FloatType)],
-     *     Causal.Types.ALEResultType,
-     *     ($, data) => {
-     *         const config = $.let({
-     *             columns: ["dose", "z", "response"],
-     *             outcome: "response",
-     *             feature: "dose",
-     *             categorical: variant('none', null),
-     *             grid_size: variant('some', 10n),
-     *             include_ci: variant('some', true),
-     *             confidence_level: variant('some', 0.95),
-     *             emulator: variant('none', null),
-     *             random_state: variant('some', 42n),
-     *         }, CausalALEConfigType);
-     *         return $.return(Causal.ale(data, config));
-     *     }
-     * );
-     * ```
-     */
-    readonly ale: import("@elaraai/east").PlatformDefinition<[MatrixType<FloatType>, StructType<{
-        /** Column names for the data matrix (one per column, in order) */
-        readonly columns: ArrayType<StringType>;
-        /** Outcome column the emulator predicts */
-        readonly outcome: StringType;
-        /** Continuous feature column to compute the ALE curve for */
-        readonly feature: StringType;
-        /** Columns holding integer category codes, one-hot encoded internally */
-        readonly categorical: OptionType<ArrayType<StringType>>;
-        /** Number of grid intervals (default 10) */
-        readonly grid_size: OptionType<IntegerType>;
-        /** Include confidence intervals (default true) */
-        readonly include_ci: OptionType<BooleanType>;
-        /** Confidence level for the CI (default 0.95) */
-        readonly confidence_level: OptionType<FloatType>;
-        /** Emulator (HistGradientBoosting) hyperparameters */
-        readonly emulator: OptionType<StructType<{
-            /** Number of boosting iterations (default 300) */
-            readonly n_estimators: OptionType<IntegerType>;
-            /** Learning rate (default 0.05) */
-            readonly learning_rate: OptionType<FloatType>;
-            /** Maximum tree depth (default unlimited) */
-            readonly max_depth: OptionType<IntegerType>;
-            /** Minimum samples per leaf (default 20; lower for small datasets) */
-            readonly min_samples_leaf: OptionType<IntegerType>;
+        /** 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`; `none` when there's no comparison group. */
+        readonly current_power: OptionType<FloatType>;
+        /** Categories both groups must be matched on (most-imbalanced confounders). */
+        readonly match_on: ArrayType<StringType>;
+        /** Ranked split options (even split first; cost-saving alternates). */
+        readonly options: ArrayType<StructType<{
+            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;
         }>>;
-        /** Random seed for the emulator */
-        readonly random_state: OptionType<IntegerType>;
-    }>], StructType<{
-        /** Feature grid values (interval edges) */
-        readonly grid: VectorType<FloatType>;
-        /** Centered ALE effect at each grid value (outcome units) */
-        readonly effect: VectorType<FloatType>;
-        /** Lower CI at each grid value (present when include_ci) */
-        readonly lower: OptionType<VectorType<FloatType>>;
-        /** Upper CI at each grid value (present when include_ci) */
-        readonly upper: OptionType<VectorType<FloatType>>;
-        /** Number of samples in each grid interval */
-        readonly size: VectorType<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 definitions */
     readonly Types: {
@@ -1569,7 +1524,7 @@ export declare const Causal: {
             readonly ips_normalized_weight: NullType;
         }>;
         readonly CausalEstimatorType: VariantType<{
-            /** Linear regression of outcome on treatment + common causes */
+            /** Linear regression of outcome on treatment + common causes (default) */
             readonly linear_regression: NullType;
             /** Inverse propensity score weighting (binary treatment only) */
             readonly propensity_score_weighting: StructType<{
@@ -1592,39 +1547,40 @@ export declare const Causal: {
             /** Average treatment effect on the controls */
             readonly atc: NullType;
         }>;
-        readonly PropensityTrimType: VariantType<{
-            /** Keep units inside the common-support overlap of treated and control propensities */
-            readonly overlap: NullType;
-            /** Keep units with propensity inside explicit bounds */
-            readonly bounds: StructType<{
-                /** Minimum propensity score to keep */
-                readonly lower: FloatType;
-                /** Maximum propensity score to keep */
-                readonly upper: FloatType;
-            }>;
-        }>;
         readonly CausalBootstrapConfigType: StructType<{
-            /** Number of bootstrap replicates */
+            /** Number of bootstrap replicates (default 200) */
             readonly reps: IntegerType;
             /** Column whose values identify clusters to resample (default: resample rows) */
             readonly cluster_column: OptionType<StringType>;
             /** Confidence level for the percentile interval (default 0.95) */
             readonly confidence_level: OptionType<FloatType>;
         }>;
-        readonly CausalEffectConfigType: StructType<{
-            /** Column names for the data matrix (one per column, in order) */
-            readonly columns: ArrayType<StringType>;
-            /** Treatment column (must be 0/1 for propensity score weighting) */
+        readonly CiType: StructType<{
+            readonly lower: FloatType;
+            readonly upper: FloatType;
+        }>;
+        readonly 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>>;
+        }>;
+        readonly CausalExperimentConfigType: StructType<{
+            /** Binary (0/1) treatment column. */
             readonly treatment: StringType;
-            /** Outcome column */
+            /** Outcome column. */
             readonly outcome: StringType;
-            /** Confounder columns to adjust for (the backdoor set) */
+            /** Confounders to adjust for (the backdoor set). */
             readonly common_causes: ArrayType<StringType>;
-            /** Columns holding integer category codes, one-hot encoded internally */
+            /** Confounder columns holding categories (string or int codes), one-hot encoded. */
             readonly categorical: OptionType<ArrayType<StringType>>;
-            /** Effect estimator (default: linear_regression) */
+            /** Estimator (default: linear_regression). */
             readonly method: OptionType<VariantType<{
-                /** Linear regression of outcome on treatment + common causes */
+                /** Linear regression of outcome on treatment + common causes (default) */
                 readonly linear_regression: NullType;
                 /** Inverse propensity score weighting (binary treatment only) */
                 readonly propensity_score_weighting: StructType<{
@@ -1639,8 +1595,8 @@ export declare const Causal: {
                     }>>;
                 }>;
             }>>;
-            /** Target population (default: ate) */
-            readonly target_units: OptionType<VariantType<{
+            /** Target population (default: ate). */
+            readonly estimand: OptionType<VariantType<{
                 /** Average treatment effect over all units */
                 readonly ate: NullType;
                 /** Average treatment effect on the treated */
@@ -1648,224 +1604,262 @@ export declare const Causal: {
                 /** Average treatment effect on the controls */
                 readonly atc: NullType;
             }>>;
-            /** Propensity trimming applied before estimation (psw only) */
-            readonly trim: OptionType<VariantType<{
-                /** Keep units inside the common-support overlap of treated and control propensities */
-                readonly overlap: NullType;
-                /** Keep units with propensity inside explicit bounds */
-                readonly bounds: StructType<{
-                    /** Minimum propensity score to keep */
-                    readonly lower: FloatType;
-                    /** Maximum propensity score to keep */
-                    readonly upper: FloatType;
-                }>;
+            /** Which robustness checks to run. */
+            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>>;
             }>>;
-            /** Bootstrap confidence interval (omit to skip CI computation) */
+            /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+            readonly dose_feature: OptionType<StringType>;
+            /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+            readonly min_overlap: OptionType<FloatType>;
+            /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+            readonly min_treatment_variation: OptionType<FloatType>;
+            /** Bootstrap CI config (default: 200 reps, 0.95). */
             readonly bootstrap: OptionType<StructType<{
-                /** Number of bootstrap replicates */
+                /** Number of bootstrap replicates (default 200) */
                 readonly reps: IntegerType;
                 /** Column whose values identify clusters to resample (default: resample rows) */
                 readonly cluster_column: OptionType<StringType>;
                 /** Confidence level for the percentile interval (default 0.95) */
                 readonly confidence_level: OptionType<FloatType>;
             }>>;
-            /** Random seed for propensity fitting and bootstrap resampling */
+            /** Random seed. */
             readonly random_state: OptionType<IntegerType>;
         }>;
-        readonly CausalRefuterType: VariantType<{
-            /** Replace treatment with a permuted placebo - effect should vanish */
-            readonly placebo_treatment: StructType<{
-                /** Number of simulations (default 100) */
-                readonly num_simulations: OptionType<IntegerType>;
-            }>;
-            /** Add an independent random common cause - effect should be unchanged */
-            readonly random_common_cause: StructType<{
-                /** Number of simulations (default 100) */
-                readonly num_simulations: OptionType<IntegerType>;
-            }>;
-            /** Re-estimate on random data subsets - effect should be stable */
-            readonly data_subset: StructType<{
-                /** Fraction of rows kept per simulation (default 0.8) */
-                readonly subset_fraction: OptionType<FloatType>;
-                /** Number of simulations (default 100) */
-                readonly num_simulations: OptionType<IntegerType>;
-            }>;
-            /**
-             * Simulate an unobserved confounder at each given strength - a
-             * sensitivity/tipping curve. Strength acts on both treatment
-             * (flip probability for binary treatment, linear coefficient otherwise)
-             * and outcome (linear coefficient).
-             */
-            readonly unobserved_common_cause: StructType<{
-                /** Confounder effect strengths to simulate, one new effect per entry */
-                readonly effect_strengths: ArrayType<FloatType>;
-            }>;
+        readonly BalanceRowType: StructType<{
+            readonly column: StringType;
+            /** 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;
+            /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+            readonly std_diff: FloatType;
         }>;
-        readonly CausalNuisanceModelType: VariantType<{
-            /** Random forest (regressor, or classifier for a discrete treatment) */
-            readonly random_forest: StructType<{
-                /** Number of trees (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 5) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-            readonly gradient_boosting: StructType<{
-                /** Number of boosting stages (default 100) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.1) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default 3) */
-                readonly max_depth: OptionType<IntegerType>;
-            }>;
-            /** Linear/logistic regression */
-            readonly linear: NullType;
+        readonly OverlapDiagnosticType: StructType<{
+            /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+            readonly treated_propensity: VectorType<FloatType>;
+            /** Propensity histogram for the control arm. */
+            readonly control_propensity: VectorType<FloatType>;
+            /** Fraction of rows inside the treated/control common support. */
+            readonly common_support_frac: FloatType;
+            /** Whether common support clears `min_overlap`. */
+            readonly positivity_ok: BooleanType;
         }>;
-        readonly CausalDMLConfigType: StructType<{
-            /** Nuisance model for the outcome stage (default: random_forest) */
-            readonly model_y: OptionType<VariantType<{
-                /** Random forest (regressor, or classifier for a discrete treatment) */
-                readonly random_forest: StructType<{
-                    /** Number of trees (default 100) */
-                    readonly n_estimators: OptionType<IntegerType>;
-                    /** Minimum samples per leaf (default 5) */
-                    readonly min_samples_leaf: OptionType<IntegerType>;
-                    /** Maximum tree depth (default unlimited) */
-                    readonly max_depth: OptionType<IntegerType>;
-                }>;
-                /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-                readonly gradient_boosting: StructType<{
-                    /** Number of boosting stages (default 100) */
-                    readonly n_estimators: OptionType<IntegerType>;
-                    /** Learning rate (default 0.1) */
-                    readonly learning_rate: OptionType<FloatType>;
-                    /** Maximum tree depth (default 3) */
-                    readonly max_depth: OptionType<IntegerType>;
-                }>;
-                /** Linear/logistic regression */
-                readonly linear: NullType;
+        readonly 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>;
             }>>;
-            /** Nuisance model for the treatment stage (default: random_forest) */
-            readonly model_t: OptionType<VariantType<{
-                /** Random forest (regressor, or classifier for a discrete treatment) */
-                readonly random_forest: StructType<{
-                    /** Number of trees (default 100) */
-                    readonly n_estimators: OptionType<IntegerType>;
-                    /** Minimum samples per leaf (default 5) */
-                    readonly min_samples_leaf: OptionType<IntegerType>;
-                    /** Maximum tree depth (default unlimited) */
-                    readonly max_depth: OptionType<IntegerType>;
-                }>;
-                /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-                readonly gradient_boosting: StructType<{
-                    /** Number of boosting stages (default 100) */
-                    readonly n_estimators: OptionType<IntegerType>;
-                    /** Learning rate (default 0.1) */
-                    readonly learning_rate: OptionType<FloatType>;
-                    /** Maximum tree depth (default 3) */
-                    readonly max_depth: OptionType<IntegerType>;
-                }>;
-                /** Linear/logistic regression */
-                readonly linear: NullType;
-            }>>;
-            /** Treat the treatment as discrete/categorical (default false) */
-            readonly discrete_treatment: OptionType<BooleanType>;
-            /** Cross-fitting folds (default 2) */
-            readonly cv_folds: OptionType<IntegerType>;
-            /** Confidence level for effect/ATE intervals (default 0.95) */
-            readonly confidence_level: OptionType<FloatType>;
-            /** Random seed */
-            readonly random_state: OptionType<IntegerType>;
         }>;
-        readonly CausalALEConfigType: StructType<{
-            /** Column names for the data matrix (one per column, in order) */
-            readonly columns: ArrayType<StringType>;
-            /** Outcome column the emulator predicts */
-            readonly outcome: StringType;
-            /** Continuous feature column to compute the ALE curve for */
+        readonly DoseResponseType: StructType<{
             readonly feature: StringType;
-            /** Columns holding integer category codes, one-hot encoded internally */
-            readonly categorical: OptionType<ArrayType<StringType>>;
-            /** Number of grid intervals (default 10) */
-            readonly grid_size: OptionType<IntegerType>;
-            /** Include confidence intervals (default true) */
-            readonly include_ci: OptionType<BooleanType>;
-            /** Confidence level for the CI (default 0.95) */
-            readonly confidence_level: OptionType<FloatType>;
-            /** Emulator (HistGradientBoosting) hyperparameters */
-            readonly emulator: OptionType<StructType<{
-                /** Number of boosting iterations (default 300) */
-                readonly n_estimators: OptionType<IntegerType>;
-                /** Learning rate (default 0.05) */
-                readonly learning_rate: OptionType<FloatType>;
-                /** Maximum tree depth (default unlimited) */
-                readonly max_depth: OptionType<IntegerType>;
-                /** Minimum samples per leaf (default 20; lower for small datasets) */
-                readonly min_samples_leaf: OptionType<IntegerType>;
-            }>>;
-            /** Random seed for the emulator */
-            readonly random_state: OptionType<IntegerType>;
+            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 CausalDMLModelBlobType: VariantType<{
-            /** Fitted EconML LinearDML estimator */
-            readonly causal_dml: StructType<{
-                /** Serialized estimator (cloudpickle) */
-                readonly data: BlobType;
-                /** Number of effect-modifier (X) features */
-                readonly n_features_x: IntegerType;
-                /** Confidence level used for effect/ATE intervals */
-                readonly confidence_level: FloatType;
-            }>;
+        readonly ExperimentVerdictType: VariantType<{
+            /** A real, robust, material effect. */
+            readonly causal: NullType;
+            /** A small but real effect, or no clear effect after adjustment. */
+            readonly modest: NullType;
+            /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+            readonly adjustment_insufficient: NullType;
+            /** No like-for-like comparison exists (positivity violated). */
+            readonly non_identifiable_positivity: NullType;
+            /** The estimand can't be formed (treatment barely varies). */
+            readonly not_estimable: StringType;
         }>;
-        readonly CausalEffectResultType: StructType<{
-            /** Point estimate of the effect (outcome units per treatment unit) */
-            readonly effect: FloatType;
-            /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-            readonly ci: OptionType<StructType<{
-                /** Lower bound */
+        readonly CausalExperimentResultType: StructType<{
+            /** The raw (unadjusted) mean difference — always computable. */
+            readonly naive: FloatType;
+            readonly naive_ci: OptionType<StructType<{
                 readonly lower: FloatType;
-                /** Upper bound */
                 readonly upper: FloatType;
             }>>;
-            /** Rows used for estimation (after trimming) */
-            readonly n_samples: IntegerType;
-            /** Treated rows used */
+            /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+            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;
-            /** Control rows used */
             readonly n_control: IntegerType;
+            readonly n_dropped: IntegerType;
+            /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+            readonly balance: ArrayType<StructType<{
+                readonly column: StringType;
+                /** 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;
+                /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+                readonly std_diff: FloatType;
+            }>>;
+            readonly overlap: StructType<{
+                /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+                readonly treated_propensity: VectorType<FloatType>;
+                /** Propensity histogram for the control arm. */
+                readonly control_propensity: VectorType<FloatType>;
+                /** Fraction of rows inside the treated/control common support. */
+                readonly common_support_frac: FloatType;
+                /** Whether common support clears `min_overlap`. */
+                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<{
+                /** A real, robust, material effect. */
+                readonly causal: NullType;
+                /** A small but real effect, or no clear effect after adjustment. */
+                readonly modest: NullType;
+                /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+                readonly adjustment_insufficient: NullType;
+                /** No like-for-like comparison exists (positivity violated). */
+                readonly non_identifiable_positivity: NullType;
+                /** The estimand can't be formed (treatment barely varies). */
+                readonly not_estimable: StringType;
+            }>;
         }>;
-        readonly CausalRefuteResultType: StructType<{
-            /** The original estimated effect being refuted */
-            readonly estimated_effect: FloatType;
-            /**
-             * Effect under the refutation. One entry for placebo/random-common-cause/
-             * data-subset; one entry per strength for unobserved_common_cause.
-             */
-            readonly new_effects: VectorType<FloatType>;
-            /** Refutation p-value where the refuter provides one */
-            readonly p_value: OptionType<FloatType>;
+        readonly 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;
         }>;
-        readonly CausalATEResultType: StructType<{
-            /** Average treatment effect over the given X */
-            readonly ate: FloatType;
-            /** Lower bound at the model's confidence level */
-            readonly lower: FloatType;
-            /** Upper bound at the model's confidence level */
-            readonly upper: FloatType;
+        readonly TrialOptionType: StructType<{
+            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;
         }>;
-        readonly ALEResultType: StructType<{
-            /** Feature grid values (interval edges) */
-            readonly grid: VectorType<FloatType>;
-            /** Centered ALE effect at each grid value (outcome units) */
-            readonly effect: VectorType<FloatType>;
-            /** Lower CI at each grid value (present when include_ci) */
-            readonly lower: OptionType<VectorType<FloatType>>;
-            /** Upper CI at each grid value (present when include_ci) */
-            readonly upper: OptionType<VectorType<FloatType>>;
-            /** Number of samples in each grid interval */
-            readonly size: VectorType<IntegerType>;
+        readonly PowerCurveType: StructType<{
+            readonly n: VectorType<IntegerType>;
+            readonly power: VectorType<FloatType>;
+        }>;
+        readonly ExperimentDesignType: StructType<{
+            readonly verdict: VariantType<{
+                /** A real, robust, material effect. */
+                readonly causal: NullType;
+                /** A small but real effect, or no clear effect after adjustment. */
+                readonly modest: NullType;
+                /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+                readonly adjustment_insufficient: NullType;
+                /** No like-for-like comparison exists (positivity violated). */
+                readonly non_identifiable_positivity: NullType;
+                /** The estimand can't be formed (treatment barely varies). */
+                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;
+            }>;
+            /** 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`; `none` when there's no comparison group. */
+            readonly current_power: OptionType<FloatType>;
+            /** Categories both groups must be matched on (most-imbalanced confounders). */
+            readonly match_on: ArrayType<StringType>;
+            /** Ranked split options (even split first; cost-saving alternates). */
+            readonly options: ArrayType<StructType<{
+                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;
+        }>;
+        readonly 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>>;
         }>;
     };
 };