Flip every signature to `(X, y, treatment, ...)` and delete the deprecation shim

[jeongyoonlee]

Part of #980 (v1.0 M1). Refs #854.

The breaking change itself: reorder every signature to (X, y, treatment, …) and delete the deprecation shim.

This lands as one change. Once a signature is reordered, existing positional calls break silently — y and treatment are both same-length arrays, so there is no TypeError to catch a swap. A partially flipped package is therefore worse than either end state, and no subset of this checklist may be released on its own.

Unblocked and scheduled. The window-closing issues are merged (#981 shim coverage, #982 tests, #983 docs, #984 migration guide), and the release schedule is fixed: the warning ships in 0.18.0 (Sep 2026), and this flip lands in v1.0 (Jun 2027) — three minor releases, roughly nine months.

The rule

X, then y, then treatment; every other parameter keeps its relative position. Already implemented as v1_order() in causalml/inference/_arg_order.py and derived per method from that method's own signature — so the target for each method is machine-readable, not hand-maintained. tests/test_fit_arg_order.py::test_v1_order pins it.

Two shapes that are not a plain swap of the leading pair, both settled and already published in docs/migration.rst:

• A suffixed pair is reordered in place, so UpliftTreeClassifier.fit → (X, y, treatment, X_val, y_val, treatment_val, sample_weight, check_input).
• Sensitivity.get_* takes p second: (X, p, treatment, y) → (X, y, treatment, p).

Scope

The authoritative list is every method carrying _arg_order_shimmed — 56 on a default install, plus 12 on the optional TF/torch/JAX backends. The window is one-shot, so each of those methods has already told users its v1.0 order, and each must arrive at exactly that order here. The checklist below is that set grouped by family:

• Meta-learners — BaseSLearner, BaseTLearner, BaseXLearner, BaseRLearner, BaseDRLearner and subclasses (XGBTRegressor, XGBRRegressor, XGBRClassifier, XGBTClassifier, BaseSClassifier, BaseTClassifier, BaseXClassifier, BaseRClassifier, BaseDRClassifier, LRSRegressor), plus bootstrap / fit_bootstrap_ensemble
• Causal trees and forests — CausalTreeRegressor (fit, fit_predict, estimate_ate, bootstrap, bootstrap_pool), CausalRandomForestRegressor
• Uplift trees and forests — UpliftTreeClassifier / _KernelUpliftTreeClassifier (fit, plus fill and prune), UpliftRandomForestClassifier / _KernelUpliftRandomForestClassifier
• IV — IVRegressor.fit → (X, y, treatment, w); BaseDRIVLearner.fit / fit_predict / estimate_ate / predict / bootstrap → (X, y, treatment, assignment, …)
• Sensitivity helpers — Sensitivity.get_prediction / get_ate_ci / get_potential_outcome_predictions → (X, y, treatment, p)
• Neural estimators — TF and JAX DragonNet, Torch and JAX CEVAE
• Standalone — PolicyLearner, TMLELearner
• CausalML's own same-instance calls — _uplift/upliftforest.py:342, _uplift/uplifttree.py:567 and meta/rlearner.py:913 call super().fit(X, treatment, y, …) positionally. The shim guards them today, so they warn nobody; once the order flips, treatment lands silently in y.
• Update every Args: docstring block to match the new order
• Delete causalml/inference/_arg_order.py, the __init_subclass__ hook in causalml/inference/serialization.py, and the six @shim_arg_order class decorators
• Rewrite tests/test_fit_arg_order.py to assert the new order rather than the deprecation (the file's docstring says to update, not delete, these tests)
• Move docs/migration.rst and the docs/changelog.rst deprecation entry to past tense — both currently describe the flip as forthcoming

Acceptance

• Every method that carried _arg_order_shimmed before this change now has X, y, treatment leading inspect.signature(...).parameters, in the order v1_order() published for it.
• No FutureWarning machinery remains; grep for _arg_order, shim_arg_order, _in_arg_order_call is empty.
• Full suite green, and the equivalence test that guards against a silent y/treatment swap is retained in flipped form.

[jeongyoonlee]

No longer blocked. The deprecation window is decided: quarterly releases, with the warning shipping in 0.18.0 (Sep 2026) and the flip landing in v1.0 (Jun 2027) — three minor releases, roughly nine months. Published in the migration guide and changelog by #993.

The four prerequisites on #980 are merged (#981–#984), so the checklist here is ready to schedule against the v1.0 target.

One addition to the checklist from #988: the same-instance super().fit(X, treatment, y, ...) calls at _uplift/upliftforest.py:342, _uplift/uplifttree.py:567 and meta/rlearner.py:913 are guarded by the shim today and warn nobody, but once the order flips treatment lands silently in y. They need converting with the rest.