rns-engine 0.8.0__tar.gz → 0.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. rns_engine-0.10.0/CAPACITY_PLANNING.md +178 -0
  2. rns_engine-0.10.0/CUDA_PARALLEL_LANES.md +100 -0
  3. rns_engine-0.10.0/MANIFEST.in +8 -0
  4. {rns_engine-0.8.0 → rns_engine-0.10.0}/PKG-INFO +111 -19
  5. rns_engine-0.10.0/PRE_CUDA_READINESS.md +72 -0
  6. rns_engine-0.8.0/src/rns_engine.egg-info/PKG-INFO → rns_engine-0.10.0/README.md +105 -39
  7. rns_engine-0.10.0/benchmarks/weighted_int32_baseline.py +423 -0
  8. rns_engine-0.10.0/colab/T4_EXACT_GEMM_BRINGUP.ipynb +152 -0
  9. {rns_engine-0.8.0 → rns_engine-0.10.0}/pyproject.toml +21 -5
  10. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/__init__.py +66 -1
  11. rns_engine-0.10.0/src/rns_engine/cuda_contract.py +281 -0
  12. rns_engine-0.10.0/src/rns_engine/exact_gemm.py +340 -0
  13. rns_engine-0.10.0/src/rns_engine/lane_plan.py +66 -0
  14. rns_engine-0.10.0/src/rns_engine/pre_cuda.py +221 -0
  15. rns_engine-0.10.0/src/rns_engine/rail_planning.py +318 -0
  16. rns_engine-0.10.0/src/rns_engine/wide.py +339 -0
  17. rns_engine-0.8.0/README.md → rns_engine-0.10.0/src/rns_engine.egg-info/PKG-INFO +131 -16
  18. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine.egg-info/SOURCES.txt +20 -1
  19. rns_engine-0.10.0/src/rns_engine.egg-info/entry_points.txt +2 -0
  20. rns_engine-0.10.0/src/rns_engine.egg-info/requires.txt +13 -0
  21. rns_engine-0.10.0/tests/test_cuda_contract.py +56 -0
  22. rns_engine-0.10.0/tests/test_exact_gemm.py +83 -0
  23. rns_engine-0.10.0/tests/test_packaging.py +40 -0
  24. rns_engine-0.10.0/tests/test_pre_cuda.py +45 -0
  25. rns_engine-0.10.0/tests/test_pre_cuda_assets.py +30 -0
  26. rns_engine-0.10.0/tests/test_rail_planning.py +170 -0
  27. rns_engine-0.10.0/tests/test_wide.py +109 -0
  28. rns_engine-0.8.0/src/rns_engine.egg-info/requires.txt +0 -5
  29. rns_engine-0.8.0/tests/test_packaging.py +0 -8
  30. {rns_engine-0.8.0 → rns_engine-0.10.0}/LICENSE +0 -0
  31. {rns_engine-0.8.0 → rns_engine-0.10.0}/setup.cfg +0 -0
  32. {rns_engine-0.8.0 → rns_engine-0.10.0}/setup.py +0 -0
  33. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/_core.cpp +0 -0
  34. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/_weighted.cpp +0 -0
  35. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/capacity.py +0 -0
  36. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/coefficients.py +0 -0
  37. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/engine.py +0 -0
  38. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/signed.py +0 -0
  39. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine/weighted.py +0 -0
  40. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine.egg-info/dependency_links.txt +0 -0
  41. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine.egg-info/not-zip-safe +0 -0
  42. {rns_engine-0.8.0 → rns_engine-0.10.0}/src/rns_engine.egg-info/top_level.txt +0 -0
  43. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_capacity.py +0 -0
  44. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_coefficients.py +0 -0
  45. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_rns.py +0 -0
  46. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_session.py +0 -0
  47. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_signed.py +0 -0
  48. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_weighted.py +0 -0
  49. {rns_engine-0.8.0 → rns_engine-0.10.0}/tests/test_weighted_benchmark.py +0 -0
@@ -0,0 +1,178 @@
1
+ # Exact GEMM Capacity Planning
2
+
3
+ `rns_engine` keeps two different safety questions separate:
4
+
5
+ 1. **Local accumulator safety:** does each raw grouped digit-plane coefficient fit the native signed accumulator, such as INT32?
6
+ 2. **Global reconstruction safety:** after positional weights are applied, does the final wide result fit uniquely inside the RNS modulus product?
7
+
8
+ A workload can pass the first test and fail the second. Version 0.8 provides exact integer-only receipts for both.
9
+
10
+ ## Local grouped-coefficient safety
11
+
12
+ For positional digit planes,
13
+
14
+ ```text
15
+ A = sum(A_i * radix**i)
16
+ B = sum(B_j * radix**j)
17
+ ```
18
+
19
+ raw coefficient `k` is:
20
+
21
+ ```text
22
+ R_k = sum_{i+j=k} GEMM(A_i, B_j)
23
+ ```
24
+
25
+ If the GEMM inner dimension is `K`, and plane entries obey magnitude bounds `L_i` and `R_j`, then:
26
+
27
+ ```text
28
+ abs(R_k) <= sum_{i+j=k} K * L_i * R_j
29
+ ```
30
+
31
+ Use:
32
+
33
+ ```python
34
+ import rns_engine as rns
35
+
36
+ local = rns.plan_grouped_coefficient_capacity(
37
+ inner_dimension=5120,
38
+ left_digit_abs_bounds=[127] * 8,
39
+ right_digit_abs_bounds=[127] * 8,
40
+ accumulator_bits=32,
41
+ )
42
+
43
+ print(local.coefficient_pair_counts)
44
+ print(local.coefficient_abs_bounds)
45
+ print(local.max_abs_bound)
46
+ print(local.minimum_signed_accumulator_bits)
47
+ local.require_safe()
48
+ ```
49
+
50
+ For eight full-magnitude INT8 planes at `K=5120`:
51
+
52
+ ```text
53
+ largest grouped coefficient = 660,643,840
54
+ minimum signed width = 31 bits
55
+ INT32 status = safe
56
+ ```
57
+
58
+ This proves the grouped Tensor Core or native INT32 outputs can remain exact locally.
59
+
60
+ ## Global RNS reconstruction safety
61
+
62
+ The reconstructed operands obey:
63
+
64
+ ```text
65
+ left_value_bound = sum(L_i * radix**i)
66
+ right_value_bound = sum(R_j * radix**j)
67
+ ```
68
+
69
+ One final GEMM output obeys:
70
+
71
+ ```text
72
+ abs(C) <= K * left_value_bound * right_value_bound + addend_bound
73
+ ```
74
+
75
+ A symmetric signed interval `[-bound, bound]` requires modulus:
76
+
77
+ ```text
78
+ minimum_modulus = 2 * bound + 1
79
+ ```
80
+
81
+ Use:
82
+
83
+ ```python
84
+ wide = rns.plan_digit_plane_gemm_capacity(
85
+ inner_dimension=5120,
86
+ radix=128,
87
+ left_digit_abs_bounds=[127] * 8,
88
+ right_digit_abs_bounds=[127] * 8,
89
+ )
90
+
91
+ print(wide.max_abs_bound)
92
+ print(wide.capacity.minimum_required_modulus)
93
+ print(wide.capacity.required_modulus_bits)
94
+ print(wide.capacity.additional_bits_required)
95
+ print(wide.current_unique)
96
+ ```
97
+
98
+ For eight full radix-128 planes per operand:
99
+
100
+ ```text
101
+ operand magnitude bound = 128**8 - 1
102
+ required signed modulus = 126 bits
103
+ current additional deficit = 71 product bits
104
+ current four-rail result = modular-only in the worst case
105
+ ```
106
+
107
+ So the same workload is locally INT32-safe but not globally unique in the current four-rail RNS range.
108
+
109
+ ## Proposed additional rails
110
+
111
+ Candidate CRT moduli can be tested explicitly:
112
+
113
+ ```python
114
+ base = rns.plan_digit_plane_gemm_capacity(
115
+ 5120,
116
+ 128,
117
+ [127] * 8,
118
+ [127] * 8,
119
+ )
120
+
121
+ candidate = base.capacity.minimum_single_coprime_modulus
122
+
123
+ expanded = rns.plan_digit_plane_gemm_capacity(
124
+ 5120,
125
+ 128,
126
+ [127] * 8,
127
+ [127] * 8,
128
+ additional_moduli=[candidate],
129
+ )
130
+
131
+ expanded.require_unique()
132
+ ```
133
+
134
+ Every proposed modulus must be greater than one and coprime with the existing modulus product and every earlier candidate.
135
+
136
+ `minimum_single_coprime_modulus` answers only the mathematical capacity question. It does **not** claim that the returned modulus is fast to reduce, appropriate for a GPU, or the best hardware rail. Reduction cost, storage width, vectorization, and reconstruction cost must be benchmarked separately.
137
+
138
+ ## General weighted-sum planning
139
+
140
+ For arbitrary exact weighted partial bounds:
141
+
142
+ ```python
143
+ plan = rns.plan_weighted_sum_capacity(
144
+ weights=[1, 128, 128**2],
145
+ term_abs_bounds=[100, 200, 300],
146
+ addend_abs_bound=7,
147
+ )
148
+
149
+ print(plan.max_abs_bound)
150
+ print(plan.current_unique)
151
+ print(plan.modulus_shortfall)
152
+ ```
153
+
154
+ For a known result bound directly:
155
+
156
+ ```python
157
+ plan = rns.plan_signed_capacity(max_abs_bound=10**30)
158
+ print(plan.minimum_required_modulus)
159
+ print(plan.additional_bits_required)
160
+ ```
161
+
162
+ ## What these receipts prove
163
+
164
+ They prove conservative worst-case capacity from the supplied exact integer bounds. They can certify:
165
+
166
+ - grouped coefficient safety for a chosen signed accumulator width;
167
+ - the exact final-result magnitude bound;
168
+ - whether the current RNS product gives unique signed reconstruction;
169
+ - how much modulus product is missing;
170
+ - whether explicit proposed CRT rails close that deficit lawfully.
171
+
172
+ They do not prove:
173
+
174
+ - that the supplied input bounds describe a real dataset tightly;
175
+ - that a proposed modulus is computationally efficient;
176
+ - GPU, CUDA, or Tensor Core speed;
177
+ - that worst-case capacity is necessary for a narrower application distribution;
178
+ - that adding rails is cheaper than chunking, rescaling, or changing the digit representation.
@@ -0,0 +1,100 @@
1
+ # Parallel Learning Lanes for CUDA Rail and Kernel Search
2
+
3
+ The CUDA search uses a shared-prior / bounded-divergence / teaching-boundary architecture.
4
+
5
+ ## Shared prior
6
+
7
+ Every lane receives the same immutable evidence body:
8
+
9
+ - identical input matrices and exact shared scales;
10
+ - identical radix-128 digit planes;
11
+ - identical required grouped INT32 outputs;
12
+ - identical seven-rail residue targets;
13
+ - identical direct Python-big-integer answer;
14
+ - identical capacity and no-wrap receipts;
15
+ - identical warmup count and measurement protocol.
16
+
17
+ No lane may redefine correctness.
18
+
19
+ ## Independent lanes
20
+
21
+ Initial lanes should differ in one controlled design choice:
22
+
23
+ - `lane-smallest-product`: extra Mersenne exponents `(11, 29, 31)`;
24
+ - `lane-balanced`: extra Mersenne exponents `(23, 24, 25)`;
25
+ - reduction-kernel variants inside each lawful profile;
26
+ - reconstruction ordering variants;
27
+ - grouped-coefficient launch/packing variants.
28
+
29
+ Inside one benchmark epoch, lanes may tune independently. Their outputs remain comparable because the shared fixture and proof laws are frozen.
30
+
31
+ ## Hard-law firewall
32
+
33
+ Before performance evidence is accepted, every lane must pass:
34
+
35
+ 1. exact grouped-partial equality;
36
+ 2. exact residue equality on every rail;
37
+ 3. exact centered reconstruction;
38
+ 4. pairwise coprimality;
39
+ 5. local INT32 safety;
40
+ 6. global signed uniqueness;
41
+ 7. deterministic fixture identity.
42
+
43
+ A fast failing lane has no score. GCD is not learned or approximated.
44
+
45
+ ## Teaching boundary
46
+
47
+ At a fixed trial boundary:
48
+
49
+ - pool lawful integer evidence: failure counts, bytes moved, launch counts, register-spill counts, and completed output counts;
50
+ - preserve timing samples with their provenance rather than averaging incompatible runs blindly;
51
+ - select one coherent kernel/configuration body as the next teacher;
52
+ - retain alternate lawful bodies in an archive to prevent premature monoculture.
53
+
54
+ The first deterministic selection tuple is:
55
+
56
+ ```text
57
+ (correctness_failures,
58
+ validation_failures,
59
+ median_elapsed_ns,
60
+ bytes_moved,
61
+ launch_count,
62
+ lane_id)
63
+ ```
64
+
65
+ Correctness and validation fields must both be zero before timing matters. `lane_id` is the fixed tie-break.
66
+
67
+ ## Epoch rule
68
+
69
+ An epoch is a fixed number of completed repetitions on a fixed matrix shape, never wall-clock duration. This keeps work membership reproducible even though elapsed time is measured.
70
+
71
+ Suggested initial epoch:
72
+
73
+ ```text
74
+ 5 warmups + 21 measured repetitions per shape/profile
75
+ ```
76
+
77
+ The next shared prior contains the winning complete kernel body plus pooled benchmark evidence. It does not average coupled CUDA source, register layouts, or launch strategies into a synthetic kernel that no lane tested.
78
+
79
+ ## What can merge and what must be selected
80
+
81
+ Merge lawfully:
82
+
83
+ - exact pass/fail counts;
84
+ - operation counts;
85
+ - byte counts;
86
+ - launch counts;
87
+ - fixture hashes;
88
+ - hardware metadata;
89
+ - independent timing samples with provenance.
90
+
91
+ Select coherently:
92
+
93
+ - CUDA kernel source;
94
+ - tile shape;
95
+ - register layout;
96
+ - reduction strategy;
97
+ - reconstruction order;
98
+ - rail profile.
99
+
100
+ The rule is: merge evidence; select a complete executable body.
@@ -0,0 +1,8 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CAPACITY_PLANNING.md
4
+ include PRE_CUDA_READINESS.md
5
+ include CUDA_PARALLEL_LANES.md
6
+ recursive-include benchmarks *.py
7
+ recursive-include colab *.ipynb
8
+ recursive-include tests *.py
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: rns_engine
3
- Version: 0.8.0
3
+ Version: 0.10.0
4
4
  Summary: Exact RNS engine with session/cache API.
5
5
  Author: Evan Wesley
6
6
  License-Expression: AGPL-3.0-only
@@ -10,15 +10,18 @@ Classifier: Programming Language :: Python :: 3.10
10
10
  Classifier: Programming Language :: Python :: 3.11
11
11
  Classifier: Programming Language :: Python :: 3.12
12
12
  Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
13
14
  Classifier: Programming Language :: C++
14
15
  Classifier: Operating System :: OS Independent
15
- Requires-Python: >=3.10
16
+ Requires-Python: <3.15,>=3.10
16
17
  Description-Content-Type: text/markdown
17
18
  License-File: LICENSE
18
19
  Requires-Dist: numpy>=1.23
19
20
  Provides-Extra: test
20
21
  Requires-Dist: pytest; extra == "test"
21
- Requires-Dist: numpy==2.2.6; extra == "test"
22
+ Requires-Dist: tomli>=1; python_version < "3.11" and extra == "test"
23
+ Requires-Dist: numpy==2.2.6; python_version < "3.14" and extra == "test"
24
+ Requires-Dist: numpy==2.4.5; python_version >= "3.14" and extra == "test"
22
25
  Dynamic: license-file
23
26
 
24
27
  # rns_engine
@@ -69,7 +72,7 @@ The centered signed interpretation lives in:
69
72
  pip install rns_engine
70
73
  ```
71
74
 
72
- Supported Python versions: **3.10–3.13**.
75
+ Supported Python versions: **3.10–3.14**.
73
76
 
74
77
  ### AVX2 note
75
78
 
@@ -299,6 +302,64 @@ See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples,
299
302
 
300
303
  ---
301
304
 
305
+ ## Pre-CUDA exact shared-scale GEMM
306
+
307
+ Version 0.9 adds the complete CPU-side oracle and integration contract for the future CUDA/T4 body. Before using GPU credits, run:
308
+
309
+ ```bash
310
+ rns-pre-cuda --report readiness.json --fixture t4_fixture.json
311
+ ```
312
+
313
+ A green receipt proves:
314
+
315
+ - both seven-rail profiles are pairwise coprime and close the 126-bit target;
316
+ - radix-128 signed digit planes round-trip exactly;
317
+ - grouped plane GEMMs fit INT32 for the frozen witness;
318
+ - weighted seven-rail reconstruction equals direct Python-big-integer GEMM;
319
+ - shared rational scales multiply exactly with no denominator GEMM;
320
+ - the portable CUDA fixture and full backend verifier agree.
321
+
322
+ The future CUDA backend must implement both methods in the contract:
323
+
324
+ ```python
325
+ class ExactPipelineBackend:
326
+ def grouped_partials(self, left_planes, right_planes):
327
+ ... # INT8 Tensor Core / cuBLASLt grouped coefficients
328
+
329
+ def weighted_rails(self, grouped_partials, weights, moduli):
330
+ ... # GPU seven-rail modular weighting and accumulation
331
+ ```
332
+
333
+ The verifier refuses a backend that produces correct GEMM partials but silently falls back to CPU RNS. See [`PRE_CUDA_READINESS.md`](PRE_CUDA_READINESS.md), [`CUDA_PARALLEL_LANES.md`](CUDA_PARALLEL_LANES.md), and [`colab/T4_EXACT_GEMM_BRINGUP.ipynb`](colab/T4_EXACT_GEMM_BRINGUP.ipynb).
334
+
335
+ ```python
336
+ import numpy as np
337
+ import rns_engine as rns
338
+
339
+ left = rns.SharedScaleMatrix(
340
+ np.array([[2**40 + 3, -17], [29, 2**35 - 5]], dtype=object),
341
+ scale=6,
342
+ )
343
+ right = rns.SharedScaleMatrix(
344
+ np.array([[31, -(2**30) + 9], [2**33 + 1, 43]], dtype=object),
345
+ scale=35,
346
+ )
347
+
348
+ receipt = rns.exact_shared_scale_gemm(
349
+ left,
350
+ right,
351
+ config=rns.WideRNSConfig.balanced_seven_rail(),
352
+ left_plane_count=8,
353
+ right_plane_count=8,
354
+ )
355
+
356
+ assert receipt.exact_match
357
+ assert receipt.output_scale == 210
358
+ result = receipt.as_matrix()
359
+ ```
360
+
361
+ ---
362
+
302
363
  ## Core API
303
364
 
304
365
  ### Rail operations
@@ -334,6 +395,31 @@ See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples,
334
395
  - `DigitPlaneGemmCapacityPlan`
335
396
  - `GroupedCoefficientCapacityPlan`
336
397
 
398
+ ### Wide reference and pre-CUDA APIs
399
+
400
+ - `WideRNSConfig.current()`
401
+ - `WideRNSConfig.smallest_product_seven_rail()`
402
+ - `WideRNSConfig.balanced_seven_rail()`
403
+ - `accumulate_weighted_int32_wide(...)`
404
+ - `SharedScaleMatrix`
405
+ - `exact_integer_matmul(...)`
406
+ - `decompose_signed_radix(...)` / `reconstruct_signed_radix(...)`
407
+ - `grouped_plane_gemm(...)` / `reconstruct_grouped_partials(...)`
408
+ - `exact_shared_scale_gemm(...)`
409
+ - `CudaGemmFixture`
410
+ - `CpuExactPipelineBackend`
411
+ - `build_cuda_gemm_fixture(...)`
412
+ - `verify_backend(...)`
413
+ - `run_pre_cuda_readiness()`
414
+ - `build_default_pre_cuda_fixture()`
415
+
416
+ ### Parallel rail-lane planning
417
+
418
+ - `build_parallel_rail_prior(capacity)`
419
+ - `RailLearningLane`
420
+ - `ParallelRailPrior`
421
+ - `search_mersenne_rails_for_capacity(...)`
422
+
337
423
  ### Scalar-broadcast encoded operations
338
424
 
339
425
  - `mul_u64(...)`
@@ -423,7 +509,7 @@ python -m pytest tests/ -v
423
509
 
424
510
  Requirements:
425
511
 
426
- - Python 3.10–3.13
512
+ - Python 3.10–3.14
427
513
  - C++17 compiler
428
514
  - Access to the build dependencies declared in `pyproject.toml`
429
515
 
@@ -453,20 +539,26 @@ rns.HAS_AVX2
453
539
 
454
540
  ## Current release
455
541
 
456
- ### v0.8.0
457
-
458
- - exact local grouped-coefficient accumulator planning
459
- - exact global digit-plane GEMM RNS-capacity planning
460
- - strict separation between local INT32 safety and global signed uniqueness
461
- - candidate CRT-modulus validation with pairwise-coprime enforcement
462
- - exact modulus shortfall and additional-bit receipts
463
- - fused native weighted signed INT32 partial accumulation
464
- - arbitrary-precision positional weights and no-wrap certificates
465
- - canonical centered signed encoding and decoding
466
- - exact dot-product and GEMM output-bound receipts
467
- - `SignedSession` high-level API
468
- - four-rail native engine (`127 × 8191 × 65536 × 524287`)
469
- - AVX2, OpenMP, and auto-dispatch kernel families
542
+ ### v0.10.0
543
+
544
+ - prebuilt CPython 3.14 wheels for Linux x86-64, macOS Intel and Apple silicon, and Windows x64
545
+ - direct native build and full test coverage on Python 3.10–3.14
546
+ - Python 3.14-compatible pybind11 and NumPy build dependencies
547
+ - configurable correctness-first CRT oracle for arbitrary pairwise-coprime rails
548
+ - two lawful seven-rail profiles closing the 126-bit eight-plane target
549
+ - exact signed radix-128 decomposition and reconstruction
550
+ - exact grouped digit-plane GEMM coefficients with strict INT32 overflow refusal
551
+ - exact shared-scale rational GEMM with integer numerator and scale receipts
552
+ - portable JSON CUDA fixture containing inputs, planes, partials, rails, and answer
553
+ - full backend contract requiring both grouped partials and GPU rail accumulation
554
+ - deterministic pre-CUDA readiness command and frozen witness
555
+ - parallel rail-lane shared-prior plan with hard correctness firewall
556
+ - Colab/T4 bring-up notebook with one isolated CUDA integration point
557
+ - exact Mersenne rail-set search and local/global capacity planners
558
+ - fused native four-rail weighted signed INT32 accumulation
559
+ - canonical centered signed encoding and no-wrap certificates
560
+
561
+ Version 0.10 changes packaging and interpreter compatibility only; it does not change the RNS arithmetic body. The seven-rail body remains a CPU correctness oracle, not a native CUDA or production-speed wide RNS kernel.
470
562
 
471
563
  ---
472
564
 
@@ -0,0 +1,72 @@
1
+ # Pre-CUDA Readiness Contract
2
+
3
+ Do not spend GPU credits until this repository's complete CPU-side readiness gate passes:
4
+
5
+ ```bash
6
+ rns-pre-cuda
7
+ ```
8
+
9
+ The command emits one JSON receipt and exits nonzero if any required condition fails.
10
+
11
+ ## What must already be proven
12
+
13
+ The gate verifies all of the following without CUDA:
14
+
15
+ 1. The eight-plane radix-128 target at `K=5120` needs a 126-bit signed modulus.
16
+ 2. The existing four rails are short by 71 product bits.
17
+ 3. Under a 31-bit-per-extra-rail ceiling, three added rails are mathematically necessary.
18
+ 4. Both retained seven-rail profiles are pairwise coprime and close the capacity deficit:
19
+ - smallest-product exponents `(11, 29, 31)`;
20
+ - balanced exponents `(23, 24, 25)`.
21
+ 5. Both profiles round-trip centered signed values, including their exact signed boundaries.
22
+ 6. Wide rail addition and multiplication agree with Python big integers.
23
+ 7. Signed radix-128 digit planes reconstruct their source integers exactly.
24
+ 8. Grouped plane GEMMs reconstruct the direct Python-big-integer GEMM exactly.
25
+ 9. Every grouped coefficient fits signed INT32 for the tested fixture.
26
+ 10. Shared-scale rational GEMM preserves the exact numerator and multiplies scale metadata exactly.
27
+ 11. The portable CUDA fixture survives a JSON round trip.
28
+ 12. A backend must reproduce both:
29
+ - grouped INT32 coefficient matrices;
30
+ - weighted seven-rail residues.
31
+ 13. Final centered reconstruction must equal the direct big-integer witness.
32
+
33
+ ## What remains for the T4
34
+
35
+ Once the gate is green, the only intentionally missing body is the CUDA implementation of the backend contract:
36
+
37
+ ```python
38
+ class ExactPipelineBackend:
39
+ def grouped_partials(left_planes, right_planes):
40
+ ... # INT8 Tensor Core / cuBLASLt body
41
+
42
+ def weighted_rails(grouped_partials, weights, moduli):
43
+ ... # CUDA modular weighting and seven-rail accumulation
44
+ ```
45
+
46
+ The verifier, fixtures, scales, exact witnesses, range receipts, candidate rail profiles, and failure rules already exist.
47
+
48
+ ## What a green gate does not prove
49
+
50
+ A green CPU gate does not prove:
51
+
52
+ - T4 Tensor Core execution;
53
+ - CUDA correctness;
54
+ - GPU reduction efficiency;
55
+ - FP16 parity or superiority;
56
+ - that either candidate rail profile is the fastest GPU profile;
57
+ - arbitrary per-element rational denominators.
58
+
59
+ Those claims require the T4 run.
60
+
61
+ ## First T4 success condition
62
+
63
+ The first GPU milestone is not speed. It is exact equivalence:
64
+
65
+ ```text
66
+ CUDA grouped partials == CPU grouped partials
67
+ CUDA seven rails == CPU seven rails
68
+ CUDA decoded numerator == direct Python integer GEMM
69
+ CUDA output scale == left scale * right scale
70
+ ```
71
+
72
+ Only after that witness passes should timing begin.