feat: measurement uncertainty for quantities and measured constants

[mpusz]

Resolves #464.

Adds uncertain<T>, a representation type carrying a value and its standard uncertainty, and teaches the library which physical constants are measured rather than exact by definition.

The model

Uncertainty is relational: in its own unit a measured constant is exactly 1, and it is the conversion factor between units that carries the uncertainty. So the conversion engine derives a factor's relative standard uncertainty from the measured constants in both units' definitions. A constant appearing on both sides cancels symbolically, which no value-level scheme can get right:

const quantity two_suns = uncertain<double>{2.0} * iau::unit_symbols::M_SUN;

std::cout << two_suns << "\n";                            // 2 ± 0 M_☉
std::cout << two_suns.in(iau::unit_symbols::M_EARTH) << "\n";  // 665892 ± 0 M_⊕   (G cancels)
std::cout << two_suns.in(kg) << "\n";                     // 3.97682e+30 ± 8.749e+25 kg

Representations opt in through the new fold_conversion_uncertainty customization point. Every other representation converts exactly and the whole mechanism, including the derivation, compiles away.

Constants

A measured constant declares its published uncertainty in its definition, as an exact magnitude, so no representation type is imposed:

named_constant<"G", mag_ratio<667'430, 100'000> * mag_power<10, -11> * ...,
               relative_standard_uncertainty{mag_ratio<22, 10> * mag_power<10, -5>}>

This makes exact-vs-measured visible to the type system via MeasuredConstant, which gates measurement_of and get_relative_standard_uncertainty. Asking for the measurement of a constant that is exact by definition does not compile: "exact by definition" and "measured infinitely precisely" are different statements.

Values are transcribed from the published CODATA tables, not recomputed from the rounded value/uncertainty pairs, which disagree in the last digit (2022 α is 1.6, not 1.5 × 10⁻¹⁰). Annotated: iau::newtonian_constant_of_gravitation and every measured constant across the three hep CODATA namespaces.

Two metrological corrections fall out:

• k_B is annotated for CODATA 2014 only, being exact since the 2019 SI redefinition.
• hep vacuum magnetic permeability moves out of the "exact across all releases" section into the per-release namespaces, for the opposite reason: exactly 4π×10⁻⁷ before 2019, measured since. The old definition was 3.6σ from the CODATA 2018 value.

Example

measurement is replaced by weighing_the_earth, a scenario rather than a feature tour: determine the mass of the Earth from a pendulum, a radius, and G, then print an uncertainty budget showing that G is some sixty times below the stopwatch noise, and that the modelling bias of a uniform sphere is larger than the random uncertainty.

Testing

Compile-time assertions pin the derivation rules (symbolic cancellation, quadrature, fractional powers, annotated constants not recursed). Runtime tests cover propagation, all three conversion spellings (.in(U), .in<Rep>(U), value_cast<U, Rep>), and the per-release CODATA values.

Verified locally on gcc-12, gcc-15, clang-16, and clang-21, plus header-set verification and the full suite (130,142 assertions). Opened as a PR so CI can confirm the rest of the matrix.

🤖 Generated with Claude Code