[codex] Add v0.5 numeric-regime mapping study

.gitignore

@@ -1,8 +1,10 @@
 /build/
+/build-*/
 /Testing/
 /external/
 /.cache/
 **/__pycache__/
+/results/v100_numeric_regime_suite.json
 *.py[cod]
 *.o
 *.a

CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable repository and research-artifact changes are recorded here.
 
+## Unreleased - v0.5.0 Numeric-Regime Mapping
+
+### Added
+
+- Public FP16 and BF16 real/complex storage contracts for FFT, FWHT, and
+  Structured 2x2, each with explicit native-width or FP32 accumulation.
+- V100 BF16-native emulation labeling so FP32-compute-and-narrow measurements
+  cannot be mistaken for native SM70 BF16 arithmetic.
+- A generated 185-cell numeric-regime space covering floating-point contracts,
+  uint32 zeta, uint32/uint64 NTT, nine length anchors where legal, and matched
+  batch neighborhoods around predicted grid-wave boundaries.
+- Resource, grid-wave, working-set, winner-crossover, and numeric-pipeline cliff
+  detection with repeated-trial confirmation rules.
+- Complete-regime selector evaluation across numeric contract, arithmetic
+  policy, batch region, and operator, with explicit promotion/regret gates.
+- An abstaining piecewise batch selector that emits stable intervals, candidate
+  sets at boundaries, and explicit unseen-contract/out-of-range policies.
+- A matching-protocol library/base/search matrix and table generator covering
+  representative FP32 FFT/FWHT and 60-bit NTT shapes, with separate search/base
+  and search/external-library ratios.
+
+### Current Evidence Boundary
+
+- Correctness, focused smoke timing, and the 736-case/2,208-sample quick screen
+  pass on V100. The screen identifies 29 confirmed and 67 ambiguous mapping
+  crossovers. This screen is discovery evidence rather than a cross-library
+  performance claim; the focused timing, counter attribution, and separate
+  matching-protocol library comparison below provide the confirmation layers.
+- Complete-regime top-3 recall is 1.0, but geometric-mean/worst regret are
+  1.047/2.078. The new selector is intentionally not promoted to runtime use.
+- Focused full-protocol timing repeats all 29 quick-confirmed neighborhoods:
+  23 retain the same direction, 3 reverse, and 3 have overlapping trial ranges.
+  All nine length-axis crossovers reproduce; instability is confined to batch
+  boundaries.
+- Twelve paired NCU profiles attribute the six unstable batch events to
+  instruction/register tradeoffs, online-composition synchronization, and one
+  actual FP64 resident-CTA capacity change. None contradicts the stable
+  length-axis regime result.
+- The conservative piecewise selector auto-selects 13.61% of leave-one-batch-
+  out shapes with 1.0016x geometric-mean and 1.0567x worst regret. It is
+  validated only for those calibrated intervals; global runtime status remains
+  `measurement-required`.
+- Adaptive full timing covers 99 weak non-boundary anchors: 66 become stable,
+  33 remain near-ties, and none reverse direction. Incorporating them raises
+  leave-one-batch-out coverage to 27.74%, with 98.84% top-1 agreement,
+  1.00013x geometric-mean regret, and 1.01112x worst regret.
+- In the representative ten-shape library/base/search matrix, searched
+  configurations improve over fixed radix-2 base mappings by 2.349x geometric
+  mean and over matched external-library rows by 1.109x. Operator-level
+  search/library ratios are 1.015x FFT, 1.054x FWHT, and 1.313x NTT. The NTT
+  external rows are archived same-machine measurements with the same protocol,
+  not interleaved measurements from the current refresh.
+- Cross-GPU transfer remains deferred until the fixed-hardware numeric and
+  workload regime model is measured and validated.
+
 ## 0.4.0 - 2026-08-05
 
 ### Added

CMakeLists.txt

@@ -277,6 +277,8 @@ if(BUILD_TESTING)
              COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/test_comprehensive_suite.py")
     add_test(NAME scaling_suite
              COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/test_scaling_suite.py")
+    add_test(NAME numeric_regime_study
+             COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/test_numeric_regime_study.py")
     add_test(NAME mapping_selector
              COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/test_mapping_selector.py")
     add_test(NAME external_baseline_suite

README.md

@@ -95,10 +95,10 @@ M = (Us, Ts, Ud, Td, Ub, Tb, Hs, Rs, Rd, Rb, L, F, Q)
 | Operator | Numeric forms | Processing-unit candidates | Mapping families |
 |:--|:--|:--|:--|
 | NTT | 32/64-bit words, compatible primes below `2^63` | radix-2/4/8, Shoup, Barrett, fused coset twiddles | baseline, local tile, Hybrid2D, compact stage, stage pipeline |
-| FFT | FP32, FP64, FP16 input with FP32 accumulation | radix-2/4/8, four-multiply, Gauss-3, thread/CTA/WMMA DFT8, FP32/FP64 cuFFTDx | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
-| FWHT | FP32, FP64 | radix-2/4/8, shared and warp-register exchange | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
+| FFT | FP16/BF16 storage with native or FP32 accumulation, FP32, FP64, legacy FP16/FP32 WMMA | radix-2/4/8, four-multiply, Gauss-3, thread/CTA/WMMA DFT8, FP32/FP64 cuFFTDx | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
+| FWHT | FP16/BF16 storage with native or FP32 accumulation, FP32, FP64 | radix-2/4/8, shared and warp-register exchange | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
 | Subset/superset zeta and Mobius | uint32 | asymmetric radix-2/4/8 | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
-| Structured 2x2 | FP32, FP64 stage matrices | parameterized radix-2/4/8; generated FP32 warp-register matrix core | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
+| Structured 2x2 | FP16/BF16 storage with native or FP32 accumulation, FP32, FP64 stage matrices | parameterized radix-2/4/8; generated FP32 warp-register matrix core | temporal tile, hierarchical, online reorder, warp hybrid, stage pipeline |
 
 The historical `xor-zeta` API name is retained as a compatibility spelling for
 its original subset-zeta behavior. See the [Operator
@@ -129,6 +129,24 @@ that observation into a processing-unit, mapping, and runtime-dispatch flow.
 Its FFT lowering now treats logical decomposition count and physical execution
 group count as independent parameters: adjacent logical segments can be fused
 without forcing an intermediate global-memory pass.
+The [numeric-regime study](docs/next_phase_numeric_regimes.md) adds FP16/BF16
+accumulation and integer controls. Its 736-case quick screen confirms that the
+best mapping changes with numeric semantics; full-protocol follow-ups and NCU
+then separate stable length transitions from unstable batch boundaries. The
+quick rows guide focused measurement rather than extend the cross-library
+claims below. The resulting
+[piecewise selector](results/v100_numeric_piecewise_report.md) safely
+auto-selects a measured stable subset (27.74% leave-one-batch-out coverage,
+1.00013x geometric-mean and 1.01112x worst regret) and explicitly requests a
+short measurement outside that subset.
+
+The matching-protocol [library/base/search comparison](docs/v100_three_way_comparison.md)
+separates mapping-search gain from external-library position. Across ten
+representative V100 shapes, searched configurations are 2.349x faster than the
+fixed radix-2 base by geometric mean and 1.109x faster than the matched
+cuFFT/Dao FHT/GPU-NTT rows. Operator-level ratios are 1.015x for FFT, 1.054x
+for FWHT, and 1.313x for NTT; these summarize the selected matrix rather than
+all precisions and shapes.
 
 ### Same-Machine Library Comparisons
 
@@ -302,10 +320,11 @@ Development priorities are tracked in [`ROADMAP.md`](ROADMAP.md), and evidence
 requirements for contributions are in [`CONTRIBUTING.md`](CONTRIBUTING.md).
 Versioned changes are recorded in [`CHANGELOG.md`](CHANGELOG.md). The completed
 v0.3.0 mapping-selection milestone is archived in
-[v0.3.0 Mapping-Selection Milestone](docs/next_phase_v0.3.md). The next study
-conditions resource cliffs and mapping preference on numeric representation,
-length, batch, layout, and processing-unit cost; its hypotheses and completion
-criteria are in [Numeric-Regime Mapping Study](docs/next_phase_numeric_regimes.md).
+[v0.3.0 Mapping-Selection Milestone](docs/next_phase_v0.3.md). The completed
+fixed-V100 v0.5 study conditions resource cliffs and mapping preference on
+numeric representation, length, batch, and processing-unit cost; its
+hypotheses, measured boundaries, manifest generator, and analysis commands are in
+[Numeric-Regime Mapping Study](docs/next_phase_numeric_regimes.md).
 
 ## Evidence Boundary
 

ROADMAP.md

@@ -12,9 +12,18 @@ runtime selection, and portable resource-cliff features. The measured
 adequate mapping key: shared-memory, register, occupancy, and batch-derived
 grid-wave effects interact.
 
-## Next Target: Numeric-Regime Mapping
-
-The next release studies the mapping method on fixed hardware before adding GPU
+## v0.5.0 Status: Numeric-Regime Mapping
+
+Status: complete for the fixed-V100 release scope. FP16/BF16 storage and
+accumulation contracts, the 736-case quick screen, all 29 confirmed-event
+full-protocol follow-ups, 12 paired NCU profiles, 99 adaptive coverage anchors,
+and the library/base/search matrix are checked in. The abstaining piecewise
+selector covers 27.74% of leave-one-batch-out shapes with 1.00013x geometric-
+mean and 1.01112x worst regret. Global selection remains
+`measurement-required`; that negative boundary is a result of this milestone,
+not an unfinished promotion step.
+
+This release studies the mapping method on fixed hardware before adding GPU
 generation as another independent variable. Its primary question is:
 
 > How do numeric representation, arithmetic semantics, workload shape, and
@@ -27,10 +36,10 @@ stride, placement, output order, and the generated physical-core choices. It
 uses orthogonal screening followed by focused scans around predicted and
 observed launch, occupancy, register, shared-memory, and bandwidth boundaries.
 
-The deliverable is a conditional regime model and a selector evaluated on
-held-out regimes, not a larger table of isolated winners. See [Numeric-Regime
-Mapping Study](docs/next_phase_numeric_regimes.md) for hypotheses, work
-packages, and completion criteria.
+The deliverable is a conditional regime model with explicit abstention and a
+selector evaluated on held-out regimes, not a larger table of isolated winners.
+See [Numeric-Regime Mapping Study](docs/next_phase_numeric_regimes.md) for the
+hypotheses, protocol, evidence, and remaining generalization boundary.
 
 ## Completed: v0.3.0 Counter-Calibrated Selection
 
@@ -66,10 +75,11 @@ artifacts, and decision gates.
 
 ## Near Term Backlog
 
-- Extend the manifest with numeric, arithmetic, layout, and processing-unit
-  descriptors, then scan boundary neighborhoods across `(logN, batch)`.
-- Train and evaluate the selector on held-out precision, arithmetic-policy,
-  batch-region, and operator/core regimes.
+- Extend the fixed-V100 regime model to stride, placement, direction,
+  normalization, coefficient policy, and output-order neighborhoods using the
+  same screen-follow-up-counter hierarchy.
+- Hold out complete numeric and workload regimes and measure where the
+  piecewise selector can expand coverage without crossing its regret gates.
 - Reduce the remaining saturated FP32 `logN=20` exchange cost and the five
   FP64 `logN=14..16` crossover deficits, preserving fixed-mapping NCU evidence.
 - Explain the Structured `logN=13..15` resource-cliff response across batch,