Build phase-1 PR 1: one name per quantity, input codes, the failure order

[troldal]

Why

This is the first of three build PRs for phase 1. It builds steps (1)–(3) of the phase-1 row of DESIGN §10.3, as revised in §12.21: B7, B4 and B6. Built items carry a new status mark, [phase 1].

What

Item	DESIGN	Change
B7	§6.3	failure::where → by and fault::evals → evaluations. New nxx::best(r) returns the solution's estimate or the failure's best as one std::optional; a search result gets a reasoned deletion instead. best_x names its remedy in a comment. New detail::is_result_v (canonical call 15).
B4	§6.3, §6.7, §7.1	A NaN or infinite input fails with non_finite_input, and equal ends with invalid_input. diff rejects a non-finite x. A nested Numerixx callable's input code becomes non_finite_value inside nxx::evaluate (§12 item 22). checked_step maps an input code that a user-written step returns directly.
B6	§6.6, §6.7, §7.2	nxx::better_than is the order's customisation point; merit_of and roots::better_than are gone, and the protocol now requires an order. R3 ranks by width: half-widths only when both widths overflow, and a NaN |f| last. It is a strict weak order that never prefers a wider enclosure. New sign_bracket precondition. A pole failure carries its estimate without the enclosure.

Decisions made during review. The maintainer made these on 2026-10-06. Each fixes a defect a reviewer reproduced.

• §12 item 22: input codes are mapped inside evaluate. Before, an input code raised in prepare or init was bit-identical to the solver's own input rejection. A stop-on-input first_of_with then depended on the order of its alternatives.
• §12 item 23: then and warm_fallback handle a stage-2 failure.
  • Both map a stage-2 input code to non_finite_value.
  • A then failure keeps stage 1's estimate, except after a pole: rule 5 requires a failure to carry its best estimate.
  • warm_fallback no longer restarts an open method at a detected pole. It used to report the pole as a success at |f| = 5.8e14.
• cl and clang-cl lay out nxx::options differently. Mixing their translation units in one program is documented as unsupported (DESIGN §5.3).
• Remaining pole cases go to phase 3. Three older pole false successes remain through chains, plus a gap in the pole check while an original endpoint survives. They are documented as known limits, with measured rows (§6.10, §7.2). They are assigned to the phase-3 open-method safeguards (§10.3).

Fixed: a pre-existing MSVC bug. On cl, a first_of nested in the first slot of another first_of got an overlapping layout, from two stacked [[msvc::no_unique_address]] members. The chain gave wrong results. first_of_t::policy_ drops the attribute, and a regression test fails on cl without the fix.

Verification

• Reviews: cpp-reviewer, numerics-reviewer, simplicity-reviewer, phase-scope-checker and docs-auditor, over four fix rounds. Every finding was reproduced before it was fixed, and each fix went back to the reviewer that found the problem. The final check found only doc corrections, which are applied.

• Tests fail without the fixes: when each fix is reverted, its new tests fail. For example, with the old order and pole payload 12 of the 21 order cases fail, and with the evaluate mapping removed 17 of 67 checks fail.

• 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	299 each
  msvc	297
  gcc-multiprecision	310
  integration	8

  The determinism golden table is unchanged.

• Compiler floor: no new language or library feature in the library. The tests add std::ranges::any_of, which is C++20 and inside the GCC 14 / Clang 19 floor. The nightly on master is green (a417eec, 2026-10-06), and the floor dispatch is planned after PR 3 (decision 7).

Next

• PR 2, tolerances: B1, the with_stop and bound siblings, and A1.
• PR 3, callbacks and combinators: B2/B3, B5 and A2, then the nightly dispatch, after asking, and the tag v2.0.0-alpha.1.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

Cross-platform numerical ordering, public error semantics, and composition changes warrant final maintainer review.

Review effort: Balanced
Findings: None

What changed in this PR

Implements phase 1’s first build step for Numerixx’s shared result types, input errors, and failure-estimate ordering.

Changes:

• Unifies diagnostic field names and adds nxx::best.
• Normalizes nested input errors and improves staged failure handling.
• Updates numerical ordering, fixes MSVC chain layout, and adds regression coverage.

File	Description
tests/​usage/​test_regularity.cpp	Uses renamed failure field.
tests/​usage/​test_composition.cpp	Tests nested error mapping.
tests/​usage/​canonical_calls.cpp	Adds canonical best usage.
tests/​structural/​consumer_warnings.cpp	Exercises best in consumer checks.
tests/​roots/​test_steps.cpp	Tests step-error normalization.
tests/​roots/​test_solvers.cpp	Updates input and pole checks.
tests/​roots/​test_results.cpp	Tests result helpers.
tests/​roots/​test_order.cpp	Tests ordering properties and extremes.
tests/​roots/​test_determinism.cpp	Updates names; preserves golden values.
tests/​roots/​test_combinators.cpp	Adds composition and layout regressions.
tests/​roots/​test_any_solver.cpp	Updates failure-field assertions.
tests/​pipes/​test_pipes.cpp	Uses unified algorithm field.
tests/​multiprecision/​test_multiprecision.cpp	Covers multiprecision errors and ordering.
tests/​deriv/​test_deriv.cpp	Tests non-finite derivative inputs.
tests/​core/​test_refined.cpp	Tests bracket error distinctions.
tests/​core/​test_criteria.cpp	Tests ordering customization requirements.
tests/​compile_fail/​solver_without_better_than.cpp	Checks missing-order diagnostics.
tests/​compile_fail/​compile_fail.cmake	Registers new rejection cases.
tests/​compile_fail/​best_search_result.cpp	Checks incompatible-result rejection.
tests/​CMakeLists.txt	Registers result and ordering tests.
MIGRATION.md	Documents changed results and errors.
include/​numerixx/​roots/​secant.hpp	Uses renamed evaluation counter.
include/​numerixx/​roots/​search.hpp	Uses renamed evaluation counter.
include/​numerixx/​roots/​newton.hpp	Updates fault accounting names.
include/​numerixx/​roots/​bracket.hpp	Updates ordering and pole payloads.
include/​numerixx/​deriv/​diff.hpp	Rejects non-finite inputs explicitly.
include/​numerixx/​core/​steps.hpp	Shares checked stepping with driver.
include/​numerixx/​core/​iterate.hpp	Adds ordering customization and error mapping.
include/​numerixx/​core/​interval.hpp	Distinguishes invalid bracket inputs.
include/​numerixx/​core/​facade.hpp	Extends missing-protocol diagnostics.
include/​numerixx/​core/​error.hpp	Renames fields and adds result helpers.
include/​numerixx/​core/​compose.hpp	Improves staged failures and chain layout.
include/​numerixx/​core/​callable.hpp	Normalizes nested input faults.
examples/​quick_tour.cpp	Corrects input-error explanation.
docs/​redesign/​PLAN.md	Records phase-1 progress.
CHANGELOG.md	Documents behavior changes and verification.

---

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