Multichain diagnostics
======================

All three functions consume numerical observations rather than run objects.
See :doc:`../user/statistics` for the workflow and
:doc:`../maintainer/measurements` for the algorithms.

Input shape and unresolved values
---------------------------------

``values`` must convert to a finite float64 array with shape (chains,records),
at least two chains and four records per chain. Ragged, nonfinite, one-dimensional
or insufficient input raises. Each method splits chains internally once;
for odd lengths it uses the first and last floor(records/2) values.
An admitted input can still yield an unresolved estimate.

rank_normalized_split_rhat
---------------------------

.. autofunction:: hcphases.rank_normalized_split_rhat

Computes the maximum of rank-normalized split Rhat and its folded version.
Folding uses absolute deviations from the pooled median. Ranks pool all split
chains and average ties. The returned dictionary includes ``rhat``, ``status``,
``components`` (rank/folded), ``within_chain_variance`` and
``between_chain_variance``. Those variance fields are on the rank-normalized
scale, not physical observable units.

If rank or folded within-chain variation vanishes, ``rhat`` is None and status
is ``"unresolved_degenerate_rank_or_folded"``. Otherwise status is
``"estimated"``. The finite-sample estimate can be slightly below one.
The function imposes no convergence threshold.

bulk_ess
---------

.. autofunction:: hcphases.bulk_ess

Rank-normalizes the once-split chains and estimates multichain effective sample
size using FFT autocovariances and an initial-positive/monotone sequence.
An estimated result includes ``ess``, ``integrated_autocorrelation_time``,
``status="estimated"``, within/between-chain variances, ``positive_pairs``,
``sample_count_after_one_split`` and ``tau_lower_bound_applied``.

Insufficient split length returns zero ESS with
``"unresolved_insufficient_split_length"``. Zero within-chain or total
variance returns zero ESS with ``"unresolved_zero_within_chain_variance"``.
Zero is an unresolved sentinel in these cases, not a physical sample-size
certificate. Antithetic histories can have estimated ESS above the retained
record count.

tail_ess
---------

.. autofunction:: hcphases.tail_ess

``probability=0.05`` must be finite and strictly between zero and 0.5.
The function estimates ESS for indicators x<=q_p and x<=q_(1-p), with pooled
empirical quantiles and internal splitting. It returns the minimum of the two
when both are estimated, otherwise ``ess=None`` and
``status="unresolved_degenerate_tail"``. The dictionary also records
``lower_quantile``, ``upper_quantile``, the full ``lower``/``upper`` ESS
reports, probability and the precise indicator definition.

Discrete values or ties can make a tail indicator constant even when the
original series varies. Such unavailability must remain explicit. None of
these three methods produces a confidence interval or a scientific pass/fail
decision for the original expectation.