Deprecate positional treatment/y in meta-learner fit() for sklearn Pipeline compat (#854)

[jeongyoonlee]

What & why

Kicks off #854 — making the meta-learners compatible with sklearn.pipeline.Pipeline, the one intentional breaking change on the v1.0 roadmap (M1).

Pipeline calls the final estimator's fit(X, y) positionally, but CausalML meta-learners take fit(X, treatment, y, ...) — y is third. In v1.0 the positional order becomes fit(X, y, treatment, ...).

Reordering two required positional arguments can't be done in one step without risking a silent y/treatment swap for existing positional callers. So this is a two-step deprecation, and this PR is step one (non-breaking):

• Positional order is unchanged. Every existing fit(X, treatment, y) call keeps working exactly as before.
• Passing treatment/y positionally now emits a FutureWarning pointing callers to keyword arguments: fit(X, y=y, treatment=treatment). Keyword calls are order-independent, so code that migrates now keeps working unchanged across the v1.0 flip.
• Step two (a later PR, targeted at v1.0): flip the positional signature to (X, y, treatment, ...) and drop the shim.

How

• A small re-entrancy-guarded decorator in BaseLearner, wired in via __init_subclass__, wraps each subclass's own fit / fit_predict / estimate_ate. This covers the whole S/T/X/R/DR family (and subclasses like XGBTRegressor) with no per-method edits, and functools.wraps preserves the real signatures for introspection.
• The guard ensures internal delegation — fit_predict → fit, subclass fit → super().fit(X, treatment, y, *args, **kwargs), estimate_ate → fit_predict → fit — warns at most once per top-level call.
• No internal call sites needed changing: CausalML's own code (metrics/sensitivity.py, dataset/synthetic.py, …) already calls these methods with keywords.

Scope

• In: the BaseLearner meta-learner family (S/T/X/R/DR + subclasses).
• Out: predict already takes X first with treatment/y optional, so Pipeline's predict(X) already works — no change needed. TMLELearner (standalone, not BaseLearner, not Pipeline-usable) and the IV/NN learners are untouched here.
• Note: reordering alone doesn't make a meta-learner a drop-in Pipeline step — treatment still needs to be threaded via sklearn metadata routing. That's a separate follow-up; this PR is the argument-order groundwork.

Tests

tests/test_fit_arg_order.py (19 cases): positional-use warning across S/T/X/R/DR, keyword silence, single-warning delegation (fit_predict / estimate_ate / subclass super().fit), signature preservation, and positional == keyword equivalence (guards against a silent y/treatment swap). Full tests/test_meta_learners.py (74) stays green.

Refs #854.