def contract_population(contract, states, points=None):
    r"""Evaluate one contract on the table its orderings live on.

    $$\text{table} = \begin{cases}\text{states} & \text{every ordering global or time-history}\\
      \text{points} & \text{otherwise}\end{cases}$$

    Parameters
    ----------
    contract : ApproximationContract
        A #1627 ordering contract [-].
    states : pandas.DataFrame
        One row per state [-].
    points : pandas.DataFrame, optional
        One row per state and flux surface, carrying the state's global and
        time-history quantities as well. Without it every contract is
        evaluated per state, and its profile orderings are then
        ``UNASSESSED`` [-].

    Returns
    -------
    pandas.DataFrame
        :func:`vaft.validation.applicability.evaluate_population` output, with
        ``attrs['evaluated_on']`` ``"states"`` or ``"points"`` [-].

    Limitations
    -----------
    A contract mixing global and profile orderings is evaluated per flux
    surface, so a state contributes one row per surface; a state without
    profiles is then absent from it.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] Issue #1629 §8-§9: per-state evaluation of state-level contracts,
       per-surface of local ones.
    """
    from vaft.validation.applicability import evaluate_population

    state_level = all(_state_quantity(a.quantity) for a in contract.assumptions)
    table = states if (state_level or points is None) else points
    evaluated = evaluate_population(contract, table)
    evaluated.attrs["evaluated_on"] = "states" if table is states else "points"
    return evaluated

def ordering_coverage(states, points=None):
    r"""The fraction of states (or profile points) with a finite value, per ordering quantity, by #1627 tier.

    $$f_q = \frac{\#\{k : q_k\ \text{finite}\}}{N}$$

    Parameters
    ----------
    states : pandas.DataFrame
        One row per state; global and time-history quantities are counted
        here [-].
    points : pandas.DataFrame, optional
        One row per state and flux surface; profile, foundational and mode
        quantities are counted here when given, else in ``states`` [-].

    Returns
    -------
    pandas.DataFrame
        One row per registered quantity: ``group``, ``tier``, ``of`` (states or
        points), ``assessed`` (count) and ``fraction``; a quantity the table
        lacks has fraction 0 [-].

    Limitations
    -----------
    Coverage counts finite values only; it says nothing about how well a
    quantity is determined.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] Issue #1627 "Data-availability tiers": the summary reports coverage
       by tier.
    """
    import pandas as pd

    from vaft.validation.orderings import ORDERING_QUANTITIES

    tier_of = {group: tier for tier, groups in COVERAGE_TIERS.items() for group in groups}
    flow = set(COVERAGE_TIERS["tier3_flow"])
    rows = []
    for name, quantity in ORDERING_QUANTITIES.items():
        table = states if (points is None or quantity.group in _STATE_GROUPS) else points
        if name in table.columns:
            values = pd.to_numeric(table[name], errors="coerce").to_numpy(dtype=float)
            assessed = int(np.isfinite(values).sum())
        else:
            assessed = 0
        rows.append({"quantity": name, "group": quantity.group,
                     "tier": "tier3_flow" if name in flow else tier_of[quantity.group],
                     "of": "states" if table is states else "points",
                     "assessed": assessed, "fraction": assessed / len(table) if len(table) else math.nan})
    return pd.DataFrame(rows).set_index("quantity")

def ordering_margins(contracts, states, points=None):
    r"""Median ordering margin and the fraction on the permitted side, per assessable ordering.

    $$m = \log_{10}(x_0/x)\ (\text{small}),\qquad m = \log_{10}(x/x_0)\ (\text{large})$$

    Parameters
    ----------
    contracts : Mapping or iterable of ApproximationContract
        The contracts whose orderings are summarised; an ordering listed by
        several is reported once [-].
    states : pandas.DataFrame
        Global and time-history quantities, one row per state [-].
    points : pandas.DataFrame, optional
        Profile quantities, one row per flux surface; ``states`` is used when
        absent [-].

    Returns
    -------
    pandas.DataFrame
        Indexed by ``"<quantity> (<ordering>)"``: ``per`` (state or point), ``n``,
        ``median_margin`` [decades] and ``permitted`` (fraction with ``m > 0``),
        sorted from the least to the most room [-].

    Processing steps
    ----------------
    1. Collect each distinct ``(quantity, ordering, threshold)`` once.
    2. Take a global or time-history quantity from ``states`` (one value per
       state, never repeated per profile point) and any other from ``points``.
    3. Margins with :func:`vaft.validation.applicability.ordering_margin`.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] Issues #1627 (margins first) and #1629 §5.
    """
    import pandas as pd

    from vaft.validation.applicability import ordering_margin

    items = contracts.values() if hasattr(contracts, "values") else contracts
    seen, rows = set(), []
    for contract in items:
        for a in contract.assumptions:
            key = (a.quantity, a.ordering, a.threshold)
            if key in seen:
                continue
            seen.add(key)
            table = states if (points is None or _state_quantity(a.quantity)) else points
            if a.quantity not in table:
                continue
            values = pd.to_numeric(table[a.quantity], errors="coerce").dropna()
            if values.empty:
                continue
            m = values.map(lambda v: ordering_margin(v, a.ordering, a.threshold)).dropna()
            if m.empty:
                continue
            rows.append({"ordering": f"{a.quantity} ({a.ordering})",
                         "per": "state" if table is states else "point", "n": int(len(m)),
                         "median_margin": float(m.median()), "permitted": float((m > 0).mean())})
    frame = pd.DataFrame(rows, columns=["ordering", "per", "n", "median_margin", "permitted"])
    return frame.set_index("ordering").sort_values("median_margin")

def ordering_table(states, *, columns: Mapping[str, str] | None = None, ion_mass_amu=1.0):
    r"""The global and time-history ordering quantities of every state in a table.

    $$\text{row}_k \mapsto \{S, d_i/a, \epsilon, \beta, \beta/\epsilon,
      \tau_{evol}/\tau_A, \tau_{age}/\tau_R\}_k$$

    Parameters
    ----------
    states : pandas.DataFrame
        One row per plasma state; the inputs are read from the columns named
        in ``columns`` and a missing column means a missing input [-].
    columns : Mapping, optional
        Input name -> column name, overriding :data:`DEFAULT_COLUMNS`
        (``minor_radius``, ``major_radius``, ``b0``, ``n_e``, ``t_e``,
        ``z_eff``, ``ln_lambda``, ``beta``, ``plasma_current``,
        ``current_rate``, ``plasma_age``) [-].
    ion_mass_amu : float, optional
        Main-ion mass number [-].

    Returns
    -------
    pandas.DataFrame
        The input index, the seven ordering columns, and ``attrs['columns']``
        recording which input column fed each argument [-].

    Processing steps
    ----------------
    1. Resolve the input columns; an absent one is a missing input.
    2. :func:`global_ordering_quantities` and
       :func:`time_history_ordering_quantities` on every row.

    Limitations
    -----------
    Profile quantities need radial profiles and are built per state with
    :func:`profile_ordering_quantities`, not here.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] Issue #1627 §2 (the summary layer) and #1629 (the VEST atlas).
    """
    import pandas as pd

    mapping = {**DEFAULT_COLUMNS, **dict(columns or {})}
    rows = []
    for _, row in states.iterrows():
        get = {name: (row[column] if column in states.columns else None) for name, column in mapping.items()}
        common = dict(minor_radius=get["minor_radius"], b0=get["b0"], n_e=get["n_e"], t_e=get["t_e"],
                      z_eff=get["z_eff"], ln_lambda=get["ln_lambda"], ion_mass_amu=ion_mass_amu)
        values = global_ordering_quantities(major_radius=get["major_radius"], beta=get["beta"], **common)
        values.update(time_history_ordering_quantities(plasma_current=get["plasma_current"],
                                                       current_rate=get["current_rate"],
                                                       plasma_age=get["plasma_age"], **common))
        rows.append(values)
    table = pd.DataFrame(rows, index=states.index)
    table.attrs["columns"] = {name: column for name, column in mapping.items() if column in states.columns}
    table.attrs["ion_mass_amu"] = float(ion_mass_amu)
    return table