Post hoc Pareto front over the metrics recorded per trial.
``pareto_front`` takes the finished rows of one study (a complete result, a rows JSONL
file or a list of rows, read by the shared reader ``_rows``) and two or more axes, each
a recorded metric name with a caller-supplied direction, and returns the rows that no
other eligible row dominates. Nothing here runs a trial, writes a file, keeps state or
touches a native result: the only side effect is reading the one file named. There is
no Pareto sampler, no vector objective, no rank, hypervolume or crowding.
Contract ``pineforge-hpo-pareto-front/v1``, algorithm ``exact_all_pairs_v1``:
* Only rows with status ``ok`` compete. Every other status is excluded with the reason
``status_<status>``. An ``ok`` row whose ``metrics`` object, or an axis key in it, is
absent is excluded as ``metric_not_recorded``; one whose axis value is ``null`` as
``metric_unavailable`` (the first reason that applies, in that order).
* An axis value of an ``ok`` row must be a finite number or ``null`` (a bool, string,
array, object, non-finite number or overflowing integer refuses the call). A
non-finite number in an axis cell of any row refuses too, as the ``NaN`` token does
when the same data is read from a file.
* Row ``a`` dominates row ``b`` when ``a`` is no worse on every axis (in that axis's
direction) and strictly better on at least one. Values are compared as exact binary64
numbers, ``-0.0`` equals ``+0.0``, and equal vectors never dominate each other: both
stay on the front. Every pair of eligible rows is compared in both directions.
* The result is ordered by ascending trial id and does not depend on the order of the
rows or of the axes. ``input_sha256`` is the SHA-256 of the sorted per-row SHA-256
digests (raw bytes) of the compact, key-sorted, ASCII JSON of
``[trial_id, status, {axis name: number as binary64, or null when absent or null}]``
for every row read; the digest does not include the directions.
* ``interpretation`` is the fixed text of ``INTERPRETATION``: what the front is not.
* The admission figure is rows read + N(N-1)/2 for N eligible rows. The call is
refused as ``pareto_resource_exceeded`` only against a ``max_work`` the caller gave.
A refusal is raised as ``ParetoError``; ``ParetoError.document()`` renders it as the
refused result document (no front). The checks run in this order, so the first defect
decides the code: axes and options (``pareto_parameter_missing`` before
``pareto_parameter_invalid``); the source (``pareto_input_invalid``,
``pareto_rows_incomplete``); the context of the rows (``pareto_context_mismatch``); the
axis names (``pareto_axis_unknown``, checked only when at least one row was read); the
axis values (``pareto_input_invalid``); ``pareto_no_eligible_rows``; the admission
figure (``pareto_resource_exceeded``).
1.9.8