Build phase-1 PR 2: role-typed tolerances, the last reasons, A1

[troldal]

Why

This is the second of three build PRs for phase 1. It builds steps (4)–(6) of the phase-1 row of DESIGN §10.3, as revised in §12.21.

What

Step	DESIGN	Change
(4) B1, criteria	§6.2, §6.8, §6.14	width_tol{abs, nxx::rel_tolerance{rel}} and the same for x_tol. The bare two-number form, a part alone, and make(T, T) are deleted with reasons. The make set is make(a), make(a, *rel) (two checks, the run-time mirror of the literal) and make(abs_tolerance, rel_tolerance). Every two-number spelling is migrated. Adds canonical calls 13 and 14.
(4) B1, solvers	§7.2	brent, bisection, secant and newton reject a validated tolerance or a part through their existing bare-number deletion, which now uses one trait, not_a_criterion_v. No new deletions; the texts gain decision 12's remedy.
(5)	§6.6	with_stop gets one sibling for anything that is not a criterion. Its text says that only width_tol bounds the error in x, x_tol only the last step and f_tol only |f(x)|. This also fixes today's false reason for with_stop(1e-10). bound::operator() gains its reason.
(6) A1	§3.5	The defaults are achievable, read from the solvers' own defaults: by static_assert for float, double and long double, and at run time for cpp_bin_float_50. The check fails when a default is made unachievable, and also when the 4·eps floor is removed.

Decided during review. The maintainer made these on 2026-10-07; DESIGN §12 item 24 records them.

• width_tol{*tol, *rel} and its x_tol twin are accepted, as a constexpr constructor plus make and a guide. DESIGN tells configurations to hold a tolerance<T>, yet adding a relative part to one failed with a 106-line CTAD error.
• The make(T, T) reason names make(a, *rel).
• A mixed-type literal narrows the absolute part, for example a double absolute part with a float relative part. This is documented.

Verification

• Reviews: cpp-reviewer, numerics-reviewer, simplicity-reviewer, phase-scope-checker and docs-auditor, with one fix round. Then a re-check, whose last two small findings I applied.

  • The C++ reviewer probed every literal, deduction and make form on GCC 16.1, Clang 22.1.8, cl 19.51 and clang-cl 22.1.3. There is no ambiguity, every misuse leaves is_invocable/is_constructible false rather than a hard error, and cl reports C2280 (the deleted declaration) rather than C2668 (an ambiguity).
  • The simplicity review cut three compile-fail cases, so §12.21's approved count holds again.

• All 12 presets pass from a fresh configure, with no warnings, and the CI format check is clean:

  Presets	Tests
  gcc, gcc-noexcept, clang, clang-asan, clang-cl, all four Emscripten presets	333 each
  msvc	331
  gcc-multiprecision	348
  integration	8

  The golden table's values are unchanged; only four literals changed spelling.

• Compiler floor: no new language or library feature in the library. The tests use std::expected::and_then, which is within the GCC 14 / Clang 19 / libstdc++ 14.3 floor. Two first-error formats are not yet seen on GCC 14 and Clang 19: Clang 19's implicit guide reaching bisection's widened deletion (the same path as today's bare-number case, which the nightly passes), and two new compile-fail cases without DELETE_REASON. The scheduled nightly will check them after merge, and the floor dispatch is planned after PR 3. The nightly on master is green (de3fca1, 2026-10-07).

Next

PR 3, callbacks and combinators: B2/B3, B5 and A2. Then the nightly dispatch (asking first) and the tag v2.0.0-alpha.1.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Compiler-sensitive deduction and diagnostic changes still need human confirmation on the supported compiler floor.

0 open findings

What changed in this PR

Implements phase-1 steps 4–6: role-typed tolerances, clearer misuse diagnostics, and checks that solver defaults remain achievable.

Changes:

• Requires named relative tolerances and supports validated tolerance pairs.
• Improves solver, with_stop, and bound-call diagnostics.
• Expands contract tests, default checks, examples, and migration guidance.

File	Description
tests/​usage/​canonical_calls.cpp	Adds mixed and run-time tolerance examples.
tests/​structural/​consumer_warnings.cpp	Migrates tolerance spellings.
tests/​roots/​test_soundness.cpp	Migrates tolerance construction.
tests/​roots/​test_solvers.cpp	Tests defaults, rejections, and remedies.
tests/​roots/​test_determinism.cpp	Migrates literals; preserves golden values.
tests/​multiprecision/​test_multiprecision.cpp	Tests multiprecision defaults and tolerances.
tests/​core/​test_refined.cpp	Tests role-typed construction and validation.
tests/​core/​test_criteria.cpp	Migrates criterion literals.
tests/​compile_fail/​x_tol_zero_zero.cpp	Updates invalid joint-tolerance case.
tests/​compile_fail/​x_tol_two_numbers.cpp	Checks bare-number rejection.
tests/​compile_fail/​x_tol_abs_part_alone.cpp	Checks absolute-part rejection.
tests/​compile_fail/​width_tol_zero_zero.cpp	Checks joint invariant rejection.
tests/​compile_fail/​width_tol_two_numbers.cpp	Checks bare-number rejection.
tests/​compile_fail/​width_tol_runtime_parts.cpp	Checks run-time literal rejection.
tests/​compile_fail/​width_tol_relative_alone.cpp	Checks relative-part rejection.
tests/​compile_fail/​width_tol_negative_abs_literal.cpp	Checks negative absolute rejection.
tests/​compile_fail/​width_tol_make_two_numbers.cpp	Checks positional factory rejection.
tests/​compile_fail/​rel_tolerance_as_tolerance.cpp	Clarifies diagnostic comment.
tests/​compile_fail/​probe_p2564_escalation.cpp	Extends mixed-constructor portability probe.
tests/​compile_fail/​compile_fail.cmake	Registers cases and diagnostic expectations.
tests/​compile_fail/​brent_with_stop_width.cpp	Updates tolerance spelling in comment.
tests/​compile_fail/​brent_validated_tolerance.cpp	Checks Brent tolerance diagnostic.
tests/​compile_fail/​bound_wrong_function.cpp	Checks bound-call diagnostic.
tests/​compile_fail/​bisection_with_stop_tolerance.cpp	Checks non-criterion diagnostic.
tests/​compile_fail/​bisection_validated_tolerance.cpp	Checks bisection tolerance diagnostic.
MIGRATION.md	Explains legacy tolerance migration.
include/​numerixx/​roots/​secant.hpp	Extends tolerance misuse diagnostics.
include/​numerixx/​roots/​newton.hpp	Extends tolerance misuse diagnostics.
include/​numerixx/​roots/​brent.hpp	Updates diagnostics and deduction guide.
include/​numerixx/​roots/​bisection.hpp	Extends tolerance misuse diagnostics.
include/​numerixx/​core/​refined.hpp	Centralizes tolerance classification traits.
include/​numerixx/​core/​facade.hpp	Adds non-criterion and bound-call reasons.
include/​numerixx/​core/​criteria.hpp	Implements role-typed tolerance construction.
examples/​quick_tour.cpp	Demonstrates updated tolerance API.
docs/​redesign/​PLAN.md	Updates phase-1 progress.
docs/​redesign/​DESIGN.md	Records contracts, decisions, and verification.
CHANGELOG.md	Records API changes and tests.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.