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

{rns_engine-0.7.0/src/rns_engine.egg-info → rns_engine-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.7.0
+Version: 0.8.0
 Summary: Exact RNS engine with session/cache API.
 Author: Evan Wesley
 License-Expression: AGPL-3.0-only
@@ -194,7 +194,7 @@ out = session.decode_signed(session.add(a, b))
 
 ## Weighted INT32 partial accumulation
 
-Version 0.7 provides the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
+Version 0.7 introduced the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
 
 Give the engine signed INT32 partial outputs with shape:
 
@@ -246,7 +246,7 @@ Important details:
 - `decode_modular()` always returns the canonical residue in `[0, M)`.
 - Empty term sets produce an exact zero result.
 
-The current implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
+The implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
 
 A precomputed receipt can also be created without materializing partial arrays:
 
@@ -260,6 +260,45 @@ certificate.require_unique()
 
 ---
 
+## Exact GEMM capacity planning
+
+Version 0.8 separates two different safety questions that must not be conflated:
+
+1. Does each grouped raw digit-plane coefficient fit the native signed accumulator?
+2. Does the final radix-weighted result fit uniquely inside the global RNS modulus product?
+
+```python
+import rns_engine as rns
+
+local = rns.plan_grouped_coefficient_capacity(
+    inner_dimension=5120,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+    accumulator_bits=32,
+)
+
+global_plan = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+assert local.max_abs_bound == 660_643_840
+assert local.safe
+assert local.minimum_signed_accumulator_bits == 31
+
+assert global_plan.capacity.required_modulus_bits == 126
+assert global_plan.capacity.additional_bits_required == 71
+assert not global_plan.current_unique
+```
+
+That workload is locally safe in INT32 but globally modular-only in the current four-rail range. The planner can also validate explicit proposed CRT moduli and rejects candidates that are not pairwise coprime with the existing product.
+
+See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples, and limits of what the receipts prove.
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -285,6 +324,16 @@ certificate.require_unique()
 - `WeightedInt32Result.decode_signed(require_unique=True)`
 - `WeightedInt32Result.decode_modular()`
 
+### Capacity planning
+
+- `plan_signed_capacity(max_abs_bound, additional_moduli=())`
+- `plan_weighted_sum_capacity(weights, term_abs_bounds, addend_abs_bound=0, additional_moduli=())`
+- `plan_digit_plane_gemm_capacity(inner_dimension, radix, left_digit_abs_bounds, right_digit_abs_bounds, ...)`
+- `plan_grouped_coefficient_capacity(inner_dimension, left_digit_abs_bounds, right_digit_abs_bounds, accumulator_bits=32)`
+- `SignedCapacityPlan`
+- `DigitPlaneGemmCapacityPlan`
+- `GroupedCoefficientCapacityPlan`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -359,7 +408,7 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 - OpenMP with one thread: **82.80 billion ops/sec**
 - OpenMP with two threads: **94.86 billion ops/sec**
 
-These measurements cover the existing affine kernels, not the new weighted INT32 orchestration path.
+These measurements cover the existing affine kernels, not weighted INT32 reconstruction or the pure-Python capacity planners.
 
 ---
 
@@ -404,14 +453,15 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.7.0
+### v0.8.0
 
+- exact local grouped-coefficient accumulator planning
+- exact global digit-plane GEMM RNS-capacity planning
+- strict separation between local INT32 safety and global signed uniqueness
+- candidate CRT-modulus validation with pairwise-coprime enforcement
+- exact modulus shortfall and additional-bit receipts
 - fused native weighted signed INT32 partial accumulation
-- one compiled pass for magnitude collection, positional weighting, and four-rail accumulation
-- staged reference body retained for exact fused-versus-staged A/B benchmarking
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
+- arbitrary-precision positional weights and no-wrap certificates
 - canonical centered signed encoding and decoding
 - exact dot-product and GEMM output-bound receipts
 - `SignedSession` high-level API

{rns_engine-0.7.0 → rns_engine-0.8.0}/README.md

@@ -171,7 +171,7 @@ out = session.decode_signed(session.add(a, b))
 
 ## Weighted INT32 partial accumulation
 
-Version 0.7 provides the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
+Version 0.7 introduced the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
 
 Give the engine signed INT32 partial outputs with shape:
 
@@ -223,7 +223,7 @@ Important details:
 - `decode_modular()` always returns the canonical residue in `[0, M)`.
 - Empty term sets produce an exact zero result.
 
-The current implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
+The implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
 
 A precomputed receipt can also be created without materializing partial arrays:
 
@@ -237,6 +237,45 @@ certificate.require_unique()
 
 ---
 
+## Exact GEMM capacity planning
+
+Version 0.8 separates two different safety questions that must not be conflated:
+
+1. Does each grouped raw digit-plane coefficient fit the native signed accumulator?
+2. Does the final radix-weighted result fit uniquely inside the global RNS modulus product?
+
+```python
+import rns_engine as rns
+
+local = rns.plan_grouped_coefficient_capacity(
+    inner_dimension=5120,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+    accumulator_bits=32,
+)
+
+global_plan = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+assert local.max_abs_bound == 660_643_840
+assert local.safe
+assert local.minimum_signed_accumulator_bits == 31
+
+assert global_plan.capacity.required_modulus_bits == 126
+assert global_plan.capacity.additional_bits_required == 71
+assert not global_plan.current_unique
+```
+
+That workload is locally safe in INT32 but globally modular-only in the current four-rail range. The planner can also validate explicit proposed CRT moduli and rejects candidates that are not pairwise coprime with the existing product.
+
+See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples, and limits of what the receipts prove.
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -262,6 +301,16 @@ certificate.require_unique()
 - `WeightedInt32Result.decode_signed(require_unique=True)`
 - `WeightedInt32Result.decode_modular()`
 
+### Capacity planning
+
+- `plan_signed_capacity(max_abs_bound, additional_moduli=())`
+- `plan_weighted_sum_capacity(weights, term_abs_bounds, addend_abs_bound=0, additional_moduli=())`
+- `plan_digit_plane_gemm_capacity(inner_dimension, radix, left_digit_abs_bounds, right_digit_abs_bounds, ...)`
+- `plan_grouped_coefficient_capacity(inner_dimension, left_digit_abs_bounds, right_digit_abs_bounds, accumulator_bits=32)`
+- `SignedCapacityPlan`
+- `DigitPlaneGemmCapacityPlan`
+- `GroupedCoefficientCapacityPlan`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -336,7 +385,7 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 - OpenMP with one thread: **82.80 billion ops/sec**
 - OpenMP with two threads: **94.86 billion ops/sec**
 
-These measurements cover the existing affine kernels, not the new weighted INT32 orchestration path.
+These measurements cover the existing affine kernels, not weighted INT32 reconstruction or the pure-Python capacity planners.
 
 ---
 
@@ -381,14 +430,15 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.7.0
+### v0.8.0
 
+- exact local grouped-coefficient accumulator planning
+- exact global digit-plane GEMM RNS-capacity planning
+- strict separation between local INT32 safety and global signed uniqueness
+- candidate CRT-modulus validation with pairwise-coprime enforcement
+- exact modulus shortfall and additional-bit receipts
 - fused native weighted signed INT32 partial accumulation
-- one compiled pass for magnitude collection, positional weighting, and four-rail accumulation
-- staged reference body retained for exact fused-versus-staged A/B benchmarking
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
+- arbitrary-precision positional weights and no-wrap certificates
 - canonical centered signed encoding and decoding
 - exact dot-product and GEMM output-bound receipts
 - `SignedSession` high-level API

{rns_engine-0.7.0 → rns_engine-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rns_engine"
-version = "0.7.0"
+version = "0.8.0"
 description = "Exact RNS engine with session/cache API."
 readme = "README.md"
 requires-python = ">=3.10"

{rns_engine-0.7.0 → rns_engine-0.8.0}/src/rns_engine/__init__.py

@@ -57,6 +57,17 @@ from .weighted import (
     accumulate_weighted_int32,
     certify_weighted_sum_bound,
 )
+from .capacity import (
+    DigitPlaneGemmCapacityPlan,
+    SignedCapacityPlan,
+    plan_digit_plane_gemm_capacity,
+    plan_signed_capacity,
+    plan_weighted_sum_capacity,
+)
+from .coefficients import (
+    GroupedCoefficientCapacityPlan,
+    plan_grouped_coefficient_capacity,
+)
 
 try:
     __version__ = _distribution_version("rns_engine")
@@ -83,6 +94,10 @@ __all__ = [
     "EncodedArray", "SessionCache", "Session", "SignedSession",
     "SignedRangeCertificate", "certify_signed_bound", "certify_signed_dot_bound",
     "WeightedInt32Result", "accumulate_weighted_int32", "certify_weighted_sum_bound",
+    "SignedCapacityPlan", "DigitPlaneGemmCapacityPlan",
+    "GroupedCoefficientCapacityPlan",
+    "plan_signed_capacity", "plan_weighted_sum_capacity",
+    "plan_digit_plane_gemm_capacity", "plan_grouped_coefficient_capacity",
     "info",
 ]
 
@@ -96,3 +111,4 @@ def info():
     print(f"  AVX2          : {'yes' if HAS_AVX2 else 'no'}")
     print("  Core APIs     : add/sub/mul/fma + raw/omp/auto scalar-broadcast family")
     print("  Bridge APIs   : weighted signed INT32 accumulation with range receipts")
+    print("  Planning APIs : local coefficient safety + global digit-plane RNS capacity")

rns_engine-0.8.0/src/rns_engine/capacity.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import gcd, prod
+from operator import index
+from typing import Any, Iterable, Sequence
+
+from ._core import M
+
+
+def _require_integer(value: Any, *, name: str) -> int:
+    try:
+        return index(value)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an integer") from exc
+
+
+def _require_nonnegative_integer(value: Any, *, name: str) -> int:
+    integer = _require_integer(value, name=name)
+    if integer < 0:
+        raise ValueError(f"{name} must be >= 0")
+    return integer
+
+
+def _require_radix(value: Any) -> int:
+    radix = _require_integer(value, name="radix")
+    if radix < 2:
+        raise ValueError("radix must be >= 2")
+    return radix
+
+
+def _nonnegative_tuple(values: Iterable[Any], *, name: str) -> tuple[int, ...]:
+    try:
+        raw = tuple(values)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an iterable of nonnegative integers") from exc
+
+    return tuple(
+        _require_nonnegative_integer(value, name=f"{name}[{position}]")
+        for position, value in enumerate(raw)
+    )
+
+
+def _integer_tuple(values: Iterable[Any], *, name: str) -> tuple[int, ...]:
+    try:
+        raw = tuple(values)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an iterable of integers") from exc
+
+    return tuple(
+        _require_integer(value, name=f"{name}[{position}]")
+        for position, value in enumerate(raw)
+    )
+
+
+def _validate_additional_moduli(values: Iterable[Any]) -> tuple[int, ...]:
+    moduli = _integer_tuple(values, name="additional_moduli")
+    running_product = int(M)
+
+    for position, modulus in enumerate(moduli):
+        if modulus <= 1:
+            raise ValueError(f"additional_moduli[{position}] must be > 1")
+
+        common_factor = gcd(running_product, modulus)
+        if common_factor != 1:
+            raise ValueError(
+                f"additional_moduli[{position}]={modulus} must be coprime with "
+                f"the existing modulus product; gcd={common_factor}"
+            )
+        running_product *= modulus
+
+    return moduli
+
+
+def _ceil_div(numerator: int, denominator: int) -> int:
+    return (numerator + denominator - 1) // denominator
+
+
+@dataclass(frozen=True, slots=True)
+class SignedCapacityPlan:
+    """Exact modulus-capacity receipt for a symmetric signed result bound.
+
+    The current engine uniquely represents every integer in ``[-bound, bound]``
+    only when its modulus is at least ``2 * bound + 1``. Optional additional
+    moduli are treated as proposed CRT rails and must be pairwise coprime with
+    the current four-rail modulus product and with one another.
+    """
+
+    max_abs_bound: int
+    additional_moduli: tuple[int, ...] = ()
+
+    def __post_init__(self) -> None:
+        bound = _require_nonnegative_integer(
+            self.max_abs_bound,
+            name="max_abs_bound",
+        )
+        moduli = _validate_additional_moduli(self.additional_moduli)
+        object.__setattr__(self, "max_abs_bound", bound)
+        object.__setattr__(self, "additional_moduli", moduli)
+
+    @property
+    def current_modulus(self) -> int:
+        return int(M)
+
+    @property
+    def additional_modulus_product(self) -> int:
+        return prod(self.additional_moduli, start=1)
+
+    @property
+    def available_modulus(self) -> int:
+        return self.current_modulus * self.additional_modulus_product
+
+    @property
+    def minimum_required_modulus(self) -> int:
+        return 2 * self.max_abs_bound + 1
+
+    @property
+    def current_unique(self) -> bool:
+        return self.current_modulus >= self.minimum_required_modulus
+
+    @property
+    def unique(self) -> bool:
+        return self.available_modulus >= self.minimum_required_modulus
+
+    @property
+    def current_headroom(self) -> int:
+        return (self.current_modulus - 1) // 2 - self.max_abs_bound
+
+    @property
+    def available_headroom(self) -> int:
+        return (self.available_modulus - 1) // 2 - self.max_abs_bound
+
+    @property
+    def modulus_shortfall(self) -> int:
+        return max(0, self.minimum_required_modulus - self.available_modulus)
+
+    @property
+    def minimum_additional_product_factor(self) -> int:
+        """Smallest exact product factor needed beyond the current modulus."""
+
+        return max(
+            1,
+            _ceil_div(self.minimum_required_modulus, self.current_modulus),
+        )
+
+    @property
+    def minimum_single_coprime_modulus(self) -> int:
+        """Smallest one-rail modulus that closes the current capacity deficit.
+
+        This is a mathematical CRT-capacity result, not a claim that the
+        returned modulus has efficient reduction or hardware properties.
+        """
+
+        candidate = self.minimum_additional_product_factor
+        if candidate <= 1:
+            return 1
+        while gcd(candidate, self.current_modulus) != 1:
+            candidate += 1
+        return candidate
+
+    @property
+    def additional_bits_required(self) -> int:
+        """Power-of-two bit budget needed beyond the current modulus product."""
+
+        factor = self.minimum_additional_product_factor
+        return 0 if factor <= 1 else (factor - 1).bit_length()
+
+    @property
+    def required_modulus_bits(self) -> int:
+        return self.minimum_required_modulus.bit_length()
+
+    @property
+    def available_modulus_bits(self) -> int:
+        return self.available_modulus.bit_length()
+
+    def require_unique(self) -> SignedCapacityPlan:
+        if not self.unique:
+            raise OverflowError(
+                "signed result is modular-only: available modulus "
+                f"{self.available_modulus} is smaller than the required modulus "
+                f"{self.minimum_required_modulus} for absolute bound "
+                f"{self.max_abs_bound}"
+            )
+        return self
+
+
+def plan_signed_capacity(
+    max_abs_bound: int,
+    additional_moduli: Sequence[int] | Iterable[int] = (),
+) -> SignedCapacityPlan:
+    """Plan exact signed capacity for a known absolute result bound."""
+
+    return SignedCapacityPlan(
+        max_abs_bound=max_abs_bound,
+        additional_moduli=tuple(additional_moduli),
+    )
+
+
+def plan_weighted_sum_capacity(
+    weights: Sequence[int] | Iterable[int],
+    term_abs_bounds: Sequence[int] | Iterable[int],
+    addend_abs_bound: int = 0,
+    additional_moduli: Sequence[int] | Iterable[int] = (),
+) -> SignedCapacityPlan:
+    """Plan capacity for ``sum(weight[t] * term[t]) + addend`` exactly."""
+
+    exact_weights = _integer_tuple(weights, name="weights")
+    exact_bounds = _nonnegative_tuple(term_abs_bounds, name="term_abs_bounds")
+    if len(exact_weights) != len(exact_bounds):
+        raise ValueError(
+            "weights and term_abs_bounds must have the same length "
+            f"({len(exact_weights)} != {len(exact_bounds)})"
+        )
+
+    addend = _require_nonnegative_integer(
+        addend_abs_bound,
+        name="addend_abs_bound",
+    )
+    bound = addend + sum(
+        abs(weight) * term_bound
+        for weight, term_bound in zip(exact_weights, exact_bounds)
+    )
+    return plan_signed_capacity(bound, additional_moduli)
+
+
+@dataclass(frozen=True, slots=True)
+class DigitPlaneGemmCapacityPlan:
+    """Exact worst-case capacity plan for positional digit-plane GEMM.
+
+    If ``A = sum(A_i * radix**i)`` and ``B = sum(B_j * radix**j)``, with
+    per-plane entry magnitude bounds ``left_digit_abs_bounds[i]`` and
+    ``right_digit_abs_bounds[j]``, then one output entry obeys::
+
+        |C| <= K * left_value_abs_bound * right_value_abs_bound + addend
+
+    This is algebraically identical to summing every plane-pair GEMM with its
+    positional weight ``radix**(i + j)``. No floating point is used.
+    """
+
+    inner_dimension: int
+    radix: int
+    left_digit_abs_bounds: tuple[int, ...]
+    right_digit_abs_bounds: tuple[int, ...]
+    addend_abs_bound: int = 0
+    additional_moduli: tuple[int, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "inner_dimension",
+            _require_nonnegative_integer(
+                self.inner_dimension,
+                name="inner_dimension",
+            ),
+        )
+        object.__setattr__(self, "radix", _require_radix(self.radix))
+        object.__setattr__(
+            self,
+            "left_digit_abs_bounds",
+            _nonnegative_tuple(
+                self.left_digit_abs_bounds,
+                name="left_digit_abs_bounds",
+            ),
+        )
+        object.__setattr__(
+            self,
+            "right_digit_abs_bounds",
+            _nonnegative_tuple(
+                self.right_digit_abs_bounds,
+                name="right_digit_abs_bounds",
+            ),
+        )
+        object.__setattr__(
+            self,
+            "addend_abs_bound",
+            _require_nonnegative_integer(
+                self.addend_abs_bound,
+                name="addend_abs_bound",
+            ),
+        )
+        object.__setattr__(
+            self,
+            "additional_moduli",
+            _validate_additional_moduli(self.additional_moduli),
+        )
+
+    @property
+    def left_plane_count(self) -> int:
+        return len(self.left_digit_abs_bounds)
+
+    @property
+    def right_plane_count(self) -> int:
+        return len(self.right_digit_abs_bounds)
+
+    @property
+    def plane_pair_count(self) -> int:
+        return self.left_plane_count * self.right_plane_count
+
+    @property
+    def grouped_coefficient_count(self) -> int:
+        if self.left_plane_count == 0 or self.right_plane_count == 0:
+            return 0
+        return self.left_plane_count + self.right_plane_count - 1
+
+    @property
+    def left_value_abs_bound(self) -> int:
+        return sum(
+            digit_bound * self.radix**position
+            for position, digit_bound in enumerate(self.left_digit_abs_bounds)
+        )
+
+    @property
+    def right_value_abs_bound(self) -> int:
+        return sum(
+            digit_bound * self.radix**position
+            for position, digit_bound in enumerate(self.right_digit_abs_bounds)
+        )
+
+    @property
+    def plane_pair_abs_bounds(self) -> tuple[int, ...]:
+        return tuple(
+            self.inner_dimension * left_bound * right_bound
+            for left_bound in self.left_digit_abs_bounds
+            for right_bound in self.right_digit_abs_bounds
+        )
+
+    @property
+    def plane_pair_weights(self) -> tuple[int, ...]:
+        return tuple(
+            self.radix ** (left_position + right_position)
+            for left_position in range(self.left_plane_count)
+            for right_position in range(self.right_plane_count)
+        )
+
+    @property
+    def max_abs_bound(self) -> int:
+        return (
+            self.inner_dimension
+            * self.left_value_abs_bound
+            * self.right_value_abs_bound
+            + self.addend_abs_bound
+        )
+
+    @property
+    def capacity(self) -> SignedCapacityPlan:
+        return plan_signed_capacity(
+            self.max_abs_bound,
+            self.additional_moduli,
+        )
+
+    @property
+    def current_unique(self) -> bool:
+        return self.capacity.current_unique
+
+    @property
+    def unique(self) -> bool:
+        return self.capacity.unique
+
+    def require_unique(self) -> DigitPlaneGemmCapacityPlan:
+        self.capacity.require_unique()
+        return self
+
+
+def plan_digit_plane_gemm_capacity(
+    inner_dimension: int,
+    radix: int,
+    left_digit_abs_bounds: Sequence[int] | Iterable[int],
+    right_digit_abs_bounds: Sequence[int] | Iterable[int],
+    addend_abs_bound: int = 0,
+    additional_moduli: Sequence[int] | Iterable[int] = (),
+) -> DigitPlaneGemmCapacityPlan:
+    """Build an exact positional digit-plane GEMM capacity receipt."""
+
+    return DigitPlaneGemmCapacityPlan(
+        inner_dimension=inner_dimension,
+        radix=radix,
+        left_digit_abs_bounds=tuple(left_digit_abs_bounds),
+        right_digit_abs_bounds=tuple(right_digit_abs_bounds),
+        addend_abs_bound=addend_abs_bound,
+        additional_moduli=tuple(additional_moduli),
+    )
+
+
+__all__ = [
+    "DigitPlaneGemmCapacityPlan",
+    "SignedCapacityPlan",
+    "plan_digit_plane_gemm_capacity",
+    "plan_signed_capacity",
+    "plan_weighted_sum_capacity",
+]

rns_engine-0.8.0/src/rns_engine/coefficients.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from operator import index
+from typing import Any, Iterable, Sequence
+
+
+def _require_integer(value: Any, *, name: str) -> int:
+    try:
+        return index(value)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an integer") from exc
+
+
+def _require_nonnegative_integer(value: Any, *, name: str) -> int:
+    integer = _require_integer(value, name=name)
+    if integer < 0:
+        raise ValueError(f"{name} must be >= 0")
+    return integer
+
+
+def _nonnegative_tuple(values: Iterable[Any], *, name: str) -> tuple[int, ...]:
+    try:
+        raw = tuple(values)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an iterable of nonnegative integers") from exc
+
+    return tuple(
+        _require_nonnegative_integer(value, name=f"{name}[{position}]")
+        for position, value in enumerate(raw)
+    )
+
+
+def _ceil_log2(value: int) -> int:
+    if value <= 1:
+        return 0
+    return (value - 1).bit_length()
+
+
+@dataclass(frozen=True, slots=True)
+class GroupedCoefficientCapacityPlan:
+    """Exact local-accumulator receipt for grouped digit-plane products.
+
+    For raw positional coefficients
+
+    ``R[k] = sum_{i+j=k} GEMM(A_i, B_j)``,
+
+    each contributing plane-pair GEMM has magnitude bound
+
+    ``inner_dimension * left_bound[i] * right_bound[j]``.
+
+    This receipt answers whether those grouped coefficients fit a signed native
+    accumulator such as INT32. It deliberately does not answer whether the
+    later radix-weighted wide reconstruction fits the global RNS modulus; that
+    is handled by :class:`DigitPlaneGemmCapacityPlan`.
+    """
+
+    inner_dimension: int
+    left_digit_abs_bounds: tuple[int, ...]
+    right_digit_abs_bounds: tuple[int, ...]
+    accumulator_bits: int = 32
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "inner_dimension",
+            _require_nonnegative_integer(
+                self.inner_dimension,
+                name="inner_dimension",
+            ),
+        )
+        object.__setattr__(
+            self,
+            "left_digit_abs_bounds",
+            _nonnegative_tuple(
+                self.left_digit_abs_bounds,
+                name="left_digit_abs_bounds",
+            ),
+        )
+        object.__setattr__(
+            self,
+            "right_digit_abs_bounds",
+            _nonnegative_tuple(
+                self.right_digit_abs_bounds,
+                name="right_digit_abs_bounds",
+            ),
+        )
+        bits = _require_integer(self.accumulator_bits, name="accumulator_bits")
+        if bits < 1:
+            raise ValueError("accumulator_bits must be >= 1")
+        object.__setattr__(self, "accumulator_bits", bits)
+
+    @property
+    def coefficient_count(self) -> int:
+        if not self.left_digit_abs_bounds or not self.right_digit_abs_bounds:
+            return 0
+        return len(self.left_digit_abs_bounds) + len(self.right_digit_abs_bounds) - 1
+
+    @property
+    def plane_pair_count(self) -> int:
+        return len(self.left_digit_abs_bounds) * len(self.right_digit_abs_bounds)
+
+    @property
+    def coefficient_pair_counts(self) -> tuple[int, ...]:
+        return tuple(
+            sum(
+                1
+                for left_position in range(len(self.left_digit_abs_bounds))
+                for right_position in range(len(self.right_digit_abs_bounds))
+                if left_position + right_position == coefficient_position
+            )
+            for coefficient_position in range(self.coefficient_count)
+        )
+
+    @property
+    def coefficient_abs_bounds(self) -> tuple[int, ...]:
+        return tuple(
+            sum(
+                self.inner_dimension
+                * self.left_digit_abs_bounds[left_position]
+                * self.right_digit_abs_bounds[right_position]
+                for left_position in range(len(self.left_digit_abs_bounds))
+                for right_position in range(len(self.right_digit_abs_bounds))
+                if left_position + right_position == coefficient_position
+            )
+            for coefficient_position in range(self.coefficient_count)
+        )
+
+    @property
+    def max_abs_bound(self) -> int:
+        return max(self.coefficient_abs_bounds, default=0)
+
+    @property
+    def signed_accumulator_limit(self) -> int:
+        return (1 << (self.accumulator_bits - 1)) - 1
+
+    @property
+    def safe(self) -> bool:
+        return self.max_abs_bound <= self.signed_accumulator_limit
+
+    @property
+    def headroom(self) -> int:
+        return self.signed_accumulator_limit - self.max_abs_bound
+
+    @property
+    def minimum_signed_accumulator_bits(self) -> int:
+        return 1 + _ceil_log2(self.max_abs_bound + 1)
+
+    def require_safe(self) -> GroupedCoefficientCapacityPlan:
+        if not self.safe:
+            raise OverflowError(
+                "grouped coefficient exceeds the signed accumulator: bound "
+                f"{self.max_abs_bound} is greater than the "
+                f"{self.accumulator_bits}-bit limit "
+                f"{self.signed_accumulator_limit}"
+            )
+        return self
+
+
+def plan_grouped_coefficient_capacity(
+    inner_dimension: int,
+    left_digit_abs_bounds: Sequence[int] | Iterable[int],
+    right_digit_abs_bounds: Sequence[int] | Iterable[int],
+    accumulator_bits: int = 32,
+) -> GroupedCoefficientCapacityPlan:
+    """Build an exact local grouped-coefficient accumulator receipt."""
+
+    return GroupedCoefficientCapacityPlan(
+        inner_dimension=inner_dimension,
+        left_digit_abs_bounds=tuple(left_digit_abs_bounds),
+        right_digit_abs_bounds=tuple(right_digit_abs_bounds),
+        accumulator_bits=accumulator_bits,
+    )
+
+
+__all__ = [
+    "GroupedCoefficientCapacityPlan",
+    "plan_grouped_coefficient_capacity",
+]

{rns_engine-0.7.0 → rns_engine-0.8.0/src/rns_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.7.0
+Version: 0.8.0
 Summary: Exact RNS engine with session/cache API.
 Author: Evan Wesley
 License-Expression: AGPL-3.0-only
@@ -194,7 +194,7 @@ out = session.decode_signed(session.add(a, b))
 
 ## Weighted INT32 partial accumulation
 
-Version 0.7 provides the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
+Version 0.7 introduced the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
 
 Give the engine signed INT32 partial outputs with shape:
 
@@ -246,7 +246,7 @@ Important details:
 - `decode_modular()` always returns the canonical residue in `[0, M)`.
 - Empty term sets produce an exact zero result.
 
-The current implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
+The implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
 
 A precomputed receipt can also be created without materializing partial arrays:
 
@@ -260,6 +260,45 @@ certificate.require_unique()
 
 ---
 
+## Exact GEMM capacity planning
+
+Version 0.8 separates two different safety questions that must not be conflated:
+
+1. Does each grouped raw digit-plane coefficient fit the native signed accumulator?
+2. Does the final radix-weighted result fit uniquely inside the global RNS modulus product?
+
+```python
+import rns_engine as rns
+
+local = rns.plan_grouped_coefficient_capacity(
+    inner_dimension=5120,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+    accumulator_bits=32,
+)
+
+global_plan = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+assert local.max_abs_bound == 660_643_840
+assert local.safe
+assert local.minimum_signed_accumulator_bits == 31
+
+assert global_plan.capacity.required_modulus_bits == 126
+assert global_plan.capacity.additional_bits_required == 71
+assert not global_plan.current_unique
+```
+
+That workload is locally safe in INT32 but globally modular-only in the current four-rail range. The planner can also validate explicit proposed CRT moduli and rejects candidates that are not pairwise coprime with the existing product.
+
+See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples, and limits of what the receipts prove.
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -285,6 +324,16 @@ certificate.require_unique()
 - `WeightedInt32Result.decode_signed(require_unique=True)`
 - `WeightedInt32Result.decode_modular()`
 
+### Capacity planning
+
+- `plan_signed_capacity(max_abs_bound, additional_moduli=())`
+- `plan_weighted_sum_capacity(weights, term_abs_bounds, addend_abs_bound=0, additional_moduli=())`
+- `plan_digit_plane_gemm_capacity(inner_dimension, radix, left_digit_abs_bounds, right_digit_abs_bounds, ...)`
+- `plan_grouped_coefficient_capacity(inner_dimension, left_digit_abs_bounds, right_digit_abs_bounds, accumulator_bits=32)`
+- `SignedCapacityPlan`
+- `DigitPlaneGemmCapacityPlan`
+- `GroupedCoefficientCapacityPlan`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -359,7 +408,7 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 - OpenMP with one thread: **82.80 billion ops/sec**
 - OpenMP with two threads: **94.86 billion ops/sec**
 
-These measurements cover the existing affine kernels, not the new weighted INT32 orchestration path.
+These measurements cover the existing affine kernels, not weighted INT32 reconstruction or the pure-Python capacity planners.
 
 ---
 
@@ -404,14 +453,15 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.7.0
+### v0.8.0
 
+- exact local grouped-coefficient accumulator planning
+- exact global digit-plane GEMM RNS-capacity planning
+- strict separation between local INT32 safety and global signed uniqueness
+- candidate CRT-modulus validation with pairwise-coprime enforcement
+- exact modulus shortfall and additional-bit receipts
 - fused native weighted signed INT32 partial accumulation
-- one compiled pass for magnitude collection, positional weighting, and four-rail accumulation
-- staged reference body retained for exact fused-versus-staged A/B benchmarking
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
+- arbitrary-precision positional weights and no-wrap certificates
 - canonical centered signed encoding and decoding
 - exact dot-product and GEMM output-bound receipts
 - `SignedSession` high-level API

{rns_engine-0.7.0 → rns_engine-0.8.0}/src/rns_engine.egg-info/SOURCES.txt

@@ -5,6 +5,8 @@ setup.py
 src/rns_engine/__init__.py
 src/rns_engine/_core.cpp
 src/rns_engine/_weighted.cpp
+src/rns_engine/capacity.py
+src/rns_engine/coefficients.py
 src/rns_engine/engine.py
 src/rns_engine/signed.py
 src/rns_engine/weighted.py
@@ -14,6 +16,8 @@ src/rns_engine.egg-info/dependency_links.txt
 src/rns_engine.egg-info/not-zip-safe
 src/rns_engine.egg-info/requires.txt
 src/rns_engine.egg-info/top_level.txt
+tests/test_capacity.py
+tests/test_coefficients.py
 tests/test_packaging.py
 tests/test_rns.py
 tests/test_session.py

rns_engine-0.8.0/tests/test_capacity.py

@@ -0,0 +1,161 @@
+import math
+
+import pytest
+
+import rns_engine as rns
+
+
+def test_single_plane_int8_gemm_fits_current_four_rail_signed_range():
+    plan = rns.plan_digit_plane_gemm_capacity(
+        inner_dimension=5120,
+        radix=128,
+        left_digit_abs_bounds=[127],
+        right_digit_abs_bounds=[127],
+    )
+
+    assert plan.plane_pair_count == 1
+    assert plan.grouped_coefficient_count == 1
+    assert plan.left_value_abs_bound == 127
+    assert plan.right_value_abs_bound == 127
+    assert plan.max_abs_bound == 82_580_480
+    assert plan.current_unique is True
+    assert plan.unique is True
+    assert plan.capacity.additional_bits_required == 0
+    assert plan.require_unique() is plan
+
+
+def test_radix128_plane_count_crosses_current_capacity_at_three_planes():
+    two_planes = rns.plan_digit_plane_gemm_capacity(
+        5120,
+        128,
+        [127, 127],
+        [127, 127],
+    )
+    three_planes = rns.plan_digit_plane_gemm_capacity(
+        5120,
+        128,
+        [127, 127, 127],
+        [127, 127, 127],
+    )
+
+    assert two_planes.left_value_abs_bound == 128**2 - 1
+    assert two_planes.current_unique is True
+    assert three_planes.left_value_abs_bound == 128**3 - 1
+    assert three_planes.current_unique is False
+    with pytest.raises(OverflowError, match="modular-only"):
+        three_planes.require_unique()
+
+
+def test_eight_full_radix128_planes_need_126_bit_modulus():
+    plan = rns.plan_digit_plane_gemm_capacity(
+        inner_dimension=5120,
+        radix=128,
+        left_digit_abs_bounds=[127] * 8,
+        right_digit_abs_bounds=[127] * 8,
+    )
+
+    full_value_bound = 128**8 - 1
+    expected_output_bound = 5120 * full_value_bound**2
+
+    assert plan.left_value_abs_bound == full_value_bound
+    assert plan.right_value_abs_bound == full_value_bound
+    assert plan.plane_pair_count == 64
+    assert plan.grouped_coefficient_count == 15
+    assert plan.max_abs_bound == expected_output_bound
+    assert plan.capacity.minimum_required_modulus == 2 * expected_output_bound + 1
+    assert plan.capacity.required_modulus_bits == 126
+    assert plan.capacity.additional_bits_required == 71
+    assert plan.current_unique is False
+
+
+def test_plane_pair_ledger_matches_factored_value_bound_exactly():
+    plan = rns.plan_digit_plane_gemm_capacity(
+        inner_dimension=37,
+        radix=16,
+        left_digit_abs_bounds=[7, 3, 1],
+        right_digit_abs_bounds=[5, 2],
+        addend_abs_bound=11,
+    )
+
+    expanded = rns.plan_weighted_sum_capacity(
+        plan.plane_pair_weights,
+        plan.plane_pair_abs_bounds,
+        addend_abs_bound=11,
+    )
+
+    assert expanded.max_abs_bound == plan.max_abs_bound
+    assert plan.plane_pair_weights == (1, 16, 16, 256, 256, 4096)
+    assert plan.plane_pair_abs_bounds == (
+        37 * 7 * 5,
+        37 * 7 * 2,
+        37 * 3 * 5,
+        37 * 3 * 2,
+        37 * 1 * 5,
+        37 * 1 * 2,
+    )
+
+
+def test_candidate_extra_rail_is_checked_by_exact_coprime_product():
+    baseline = rns.plan_digit_plane_gemm_capacity(
+        5120,
+        128,
+        [127] * 8,
+        [127] * 8,
+    )
+    extra_modulus = baseline.capacity.minimum_single_coprime_modulus
+
+    expanded = rns.plan_digit_plane_gemm_capacity(
+        5120,
+        128,
+        [127] * 8,
+        [127] * 8,
+        additional_moduli=[extra_modulus],
+    )
+
+    assert math.gcd(extra_modulus, rns.M) == 1
+    assert expanded.capacity.available_modulus >= expanded.capacity.minimum_required_modulus
+    assert expanded.unique is True
+    assert expanded.require_unique() is expanded
+
+
+def test_capacity_planner_rejects_non_coprime_or_invalid_candidate_rails():
+    with pytest.raises(ValueError, match="coprime"):
+        rns.plan_signed_capacity(1, additional_moduli=[127])
+
+    with pytest.raises(ValueError, match="coprime"):
+        rns.plan_signed_capacity(1, additional_moduli=[3, 3])
+
+    with pytest.raises(ValueError, match="> 1"):
+        rns.plan_signed_capacity(1, additional_moduli=[1])
+
+
+def test_capacity_planner_uses_exact_integer_inputs_only():
+    with pytest.raises(TypeError, match="max_abs_bound"):
+        rns.plan_signed_capacity(1.5)
+
+    with pytest.raises(ValueError, match="max_abs_bound"):
+        rns.plan_signed_capacity(-1)
+
+    with pytest.raises(ValueError, match="radix"):
+        rns.plan_digit_plane_gemm_capacity(1, 1, [1], [1])
+
+    with pytest.raises(ValueError, match=r"left_digit_abs_bounds\[0\]"):
+        rns.plan_digit_plane_gemm_capacity(1, 2, [-1], [1])
+
+    with pytest.raises(ValueError, match="same length"):
+        rns.plan_weighted_sum_capacity([1, 2], [3])
+
+
+def test_empty_digit_plane_body_reduces_to_addend_capacity():
+    plan = rns.plan_digit_plane_gemm_capacity(
+        inner_dimension=5120,
+        radix=128,
+        left_digit_abs_bounds=[],
+        right_digit_abs_bounds=[127],
+        addend_abs_bound=9,
+    )
+
+    assert plan.plane_pair_count == 0
+    assert plan.grouped_coefficient_count == 0
+    assert plan.max_abs_bound == 9
+    assert plan.current_unique is True

rns_engine-0.8.0/tests/test_coefficients.py

@@ -0,0 +1,110 @@
+import pytest
+
+import rns_engine as rns
+
+
+def test_single_int8_plane_has_expected_int32_bound():
+    plan = rns.plan_grouped_coefficient_capacity(
+        inner_dimension=5120,
+        left_digit_abs_bounds=[127],
+        right_digit_abs_bounds=[127],
+    )
+
+    assert plan.coefficient_count == 1
+    assert plan.plane_pair_count == 1
+    assert plan.coefficient_pair_counts == (1,)
+    assert plan.coefficient_abs_bounds == (82_580_480,)
+    assert plan.max_abs_bound == 82_580_480
+    assert plan.safe is True
+    assert plan.minimum_signed_accumulator_bits == 28
+    assert plan.require_safe() is plan
+
+
+def test_eight_plane_grouped_coefficients_fit_int32_while_global_result_does_not():
+    local = rns.plan_grouped_coefficient_capacity(
+        inner_dimension=5120,
+        left_digit_abs_bounds=[127] * 8,
+        right_digit_abs_bounds=[127] * 8,
+        accumulator_bits=32,
+    )
+    global_plan = rns.plan_digit_plane_gemm_capacity(
+        inner_dimension=5120,
+        radix=128,
+        left_digit_abs_bounds=[127] * 8,
+        right_digit_abs_bounds=[127] * 8,
+    )
+
+    expected_pair_counts = (1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1)
+    one_pair_bound = 82_580_480
+
+    assert local.coefficient_pair_counts == expected_pair_counts
+    assert local.coefficient_abs_bounds == tuple(
+        count * one_pair_bound for count in expected_pair_counts
+    )
+    assert local.max_abs_bound == 660_643_840
+    assert local.minimum_signed_accumulator_bits == 31
+    assert local.headroom == 1_486_839_807
+    assert local.safe is True
+    assert global_plan.current_unique is False
+    assert global_plan.capacity.required_modulus_bits == 126
+
+
+def test_grouped_coefficient_plan_detects_int32_overflow():
+    plan = rns.plan_grouped_coefficient_capacity(
+        inner_dimension=20_000,
+        left_digit_abs_bounds=[127] * 8,
+        right_digit_abs_bounds=[127] * 8,
+        accumulator_bits=32,
+    )
+
+    assert plan.max_abs_bound == 20_000 * 8 * 127 * 127
+    assert plan.safe is False
+    assert plan.headroom < 0
+    assert plan.minimum_signed_accumulator_bits == 33
+    with pytest.raises(OverflowError, match="exceeds"):
+        plan.require_safe()
+
+
+def test_grouped_bounds_match_manual_nonuniform_convolution():
+    plan = rns.plan_grouped_coefficient_capacity(
+        inner_dimension=11,
+        left_digit_abs_bounds=[7, 3, 1],
+        right_digit_abs_bounds=[5, 2],
+    )
+
+    assert plan.coefficient_pair_counts == (1, 2, 2, 1)
+    assert plan.coefficient_abs_bounds == (
+        11 * (7 * 5),
+        11 * (7 * 2 + 3 * 5),
+        11 * (3 * 2 + 1 * 5),
+        11 * (1 * 2),
+    )
+
+
+def test_empty_plane_body_has_zero_local_bound():
+    plan = rns.plan_grouped_coefficient_capacity(
+        inner_dimension=5120,
+        left_digit_abs_bounds=[],
+        right_digit_abs_bounds=[127],
+    )
+
+    assert plan.coefficient_count == 0
+    assert plan.coefficient_pair_counts == ()
+    assert plan.coefficient_abs_bounds == ()
+    assert plan.max_abs_bound == 0
+    assert plan.minimum_signed_accumulator_bits == 1
+    assert plan.safe is True
+
+
+def test_grouped_coefficient_inputs_are_strict_integers():
+    with pytest.raises(TypeError, match="inner_dimension"):
+        rns.plan_grouped_coefficient_capacity(1.5, [1], [1])
+
+    with pytest.raises(ValueError, match="inner_dimension"):
+        rns.plan_grouped_coefficient_capacity(-1, [1], [1])
+
+    with pytest.raises(ValueError, match=r"left_digit_abs_bounds\[0\]"):
+        rns.plan_grouped_coefficient_capacity(1, [-1], [1])
+
+    with pytest.raises(ValueError, match="accumulator_bits"):
+        rns.plan_grouped_coefficient_capacity(1, [1], [1], accumulator_bits=0)