rns-engine 0.4.1__tar.gz → 0.5.0__tar.gz

{rns_engine-0.4.1/src/rns_engine.egg-info → rns_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.4.1
+Version: 0.5.0
 Summary: Exact RNS engine with session/cache API.
 Author: Evan Wesley
 License-Expression: AGPL-3.0-only
@@ -109,12 +109,86 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 
 ---
 
+## Centered signed arithmetic and range certificates
+
+The native core computes exact residues modulo `M`. Version 0.5 adds a canonical signed view over:
+
+```text
+[-M/2, M/2 - 1]
+=
+[-17,871,445,090,598,912, 17,871,445,090,598,911]
+```
+
+```python
+import numpy as np
+import rns_engine as rns
+
+values = np.array([-5, 0, 7], dtype=np.int64)
+rails = rns.encode_signed(values)
+round_trip = rns.decode_signed(*rails)
+
+assert np.array_equal(round_trip, values)
+```
+
+`encode_signed(...)` rejects values outside the centered interval instead of silently wrapping them modulo `M`.
+
+A centered decoding is a canonical interpretation of a residue. It is **not by itself proof that an unknown mathematical result did not wrap**. Unique signed reconstruction requires an independent strict magnitude bound:
+
+```text
+|result| < M/2
+```
+
+Use a range certificate before claiming that a residue is the unique signed integer result:
+
+```python
+certificate = rns.certify_signed_bound(max_abs_bound=1_000_000)
+certificate.require_unique()
+
+print(certificate.headroom)
+print(certificate.minimum_required_modulus)
+```
+
+For a signed dot product or one GEMM output entry, the engine can build the worst-case receipt directly:
+
+```python
+certificate = rns.certify_signed_dot_bound(
+    inner_dimension=5120,
+    left_abs_bound=127,
+    right_abs_bound=127,
+)
+
+assert certificate.max_abs_bound == 82_580_480
+assert certificate.unique
+certificate.require_unique()
+```
+
+This uses the exact conservative law:
+
+```text
+output bound
+=
+inner_dimension × left bound × right bound + addend bound
+```
+
+`SignedSession` exposes the existing residue arithmetic with signed external values:
+
+```python
+s = rns.SignedSession()
+a = s.encode_signed([-5, 7])
+b = s.encode_signed([3, -10])
+out = s.decode_signed(s.add(a, b))
+```
+
+---
+
 ## Core API
 
 ### Encoded rail API
 
 * `rns.encode(x)` → `(r0, r1, r2, r3)`
 * `rns.decode(r0, r1, r2, r3)` → `uint64[]`
+* `rns.encode_signed(x)` → strict centered signed encoding
+* `rns.decode_signed(r0, r1, r2, r3)` → canonical `int64[]`
 * `rns.add(*ea, *eb)`
 * `rns.sub(*ea, *eb)`
 * `rns.mul(*ea, *eb)`
@@ -122,6 +196,15 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 * `rns.fma(*ea, *eb, *ec)`
 * `rns.op(*ea, *eb, code)` where `0=add 1=mul 2=sub 3=div`
 
+### Range-certificate API
+
+* `rns.certify_signed_bound(max_abs_bound)`
+* `rns.certify_signed_dot_bound(inner_dimension, left_abs_bound, right_abs_bound, addend_abs_bound=0)`
+* `SignedRangeCertificate.unique`
+* `SignedRangeCertificate.headroom`
+* `SignedRangeCertificate.minimum_required_modulus`
+* `SignedRangeCertificate.require_unique()`
+
 ### Scalar-broadcast encoded API
 
 These avoid materializing full constant arrays in Python:
@@ -159,6 +242,7 @@ Auto-dispatch variants:
 ### High-level API
 
 * `rns.Session`
+* `rns.SignedSession`
 * `rns.SessionCache`
 * `rns.EncodedArray`
 
@@ -208,7 +292,9 @@ def make_invertible_divisor(b):
 ## Data model
 
 * input arrays to `encode(...)` are treated as `uint64`
-* values outside `[0, M)` are reduced mod `M` during encode
+* values outside `[0, M)` are reduced mod `M` during unsigned encode
+* `encode_signed(...)` accepts only integers in `[-M/2, M/2 - 1]` and refuses silent wrapping
+* `decode_signed(...)` returns the canonical centered `int64` view
 * rails are returned as:
   * `r0`: `uint16`
   * `r1`: `uint16`
@@ -251,7 +337,8 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 ### Verification status
 
 * correctness sanity checks passed
-* full test suite passed: **50 / 50**
+* the full suite is exercised on Linux, macOS, and Windows across Python 3.10–3.13
+* built wheels are installed and tested before release
 
 ---
 
@@ -310,6 +397,9 @@ import rns_engine as rns
 rns.info()
 
 rns.M
+rns.HALF_M
+rns.SIGNED_MIN
+rns.SIGNED_MAX
 rns.M0
 rns.M1
 rns.M2
@@ -321,9 +411,13 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.4.1
+### v0.5.0
 
-* Maintenance release: repaired packaging metadata, cross-platform wheel builds, and Python 3.10–3.13 CI; arithmetic core unchanged
+* canonical centered signed encoding and decoding
+* strict signed input validation with no silent modular wrapping
+* signed uniqueness certificates using the law `|result| < M/2`
+* exact dot-product and GEMM output-bound receipts
+* `SignedSession` high-level API
 * 4-rail engine (`127 × 8191 × 65536 × 524287`)
 * AVX2-accelerated encoded kernels
 * fused `fma(...)`

{rns_engine-0.4.1 → rns_engine-0.5.0}/README.md

@@ -86,12 +86,86 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 
 ---
 
+## Centered signed arithmetic and range certificates
+
+The native core computes exact residues modulo `M`. Version 0.5 adds a canonical signed view over:
+
+```text
+[-M/2, M/2 - 1]
+=
+[-17,871,445,090,598,912, 17,871,445,090,598,911]
+```
+
+```python
+import numpy as np
+import rns_engine as rns
+
+values = np.array([-5, 0, 7], dtype=np.int64)
+rails = rns.encode_signed(values)
+round_trip = rns.decode_signed(*rails)
+
+assert np.array_equal(round_trip, values)
+```
+
+`encode_signed(...)` rejects values outside the centered interval instead of silently wrapping them modulo `M`.
+
+A centered decoding is a canonical interpretation of a residue. It is **not by itself proof that an unknown mathematical result did not wrap**. Unique signed reconstruction requires an independent strict magnitude bound:
+
+```text
+|result| < M/2
+```
+
+Use a range certificate before claiming that a residue is the unique signed integer result:
+
+```python
+certificate = rns.certify_signed_bound(max_abs_bound=1_000_000)
+certificate.require_unique()
+
+print(certificate.headroom)
+print(certificate.minimum_required_modulus)
+```
+
+For a signed dot product or one GEMM output entry, the engine can build the worst-case receipt directly:
+
+```python
+certificate = rns.certify_signed_dot_bound(
+    inner_dimension=5120,
+    left_abs_bound=127,
+    right_abs_bound=127,
+)
+
+assert certificate.max_abs_bound == 82_580_480
+assert certificate.unique
+certificate.require_unique()
+```
+
+This uses the exact conservative law:
+
+```text
+output bound
+=
+inner_dimension × left bound × right bound + addend bound
+```
+
+`SignedSession` exposes the existing residue arithmetic with signed external values:
+
+```python
+s = rns.SignedSession()
+a = s.encode_signed([-5, 7])
+b = s.encode_signed([3, -10])
+out = s.decode_signed(s.add(a, b))
+```
+
+---
+
 ## Core API
 
 ### Encoded rail API
 
 * `rns.encode(x)` → `(r0, r1, r2, r3)`
 * `rns.decode(r0, r1, r2, r3)` → `uint64[]`
+* `rns.encode_signed(x)` → strict centered signed encoding
+* `rns.decode_signed(r0, r1, r2, r3)` → canonical `int64[]`
 * `rns.add(*ea, *eb)`
 * `rns.sub(*ea, *eb)`
 * `rns.mul(*ea, *eb)`
@@ -99,6 +173,15 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 * `rns.fma(*ea, *eb, *ec)`
 * `rns.op(*ea, *eb, code)` where `0=add 1=mul 2=sub 3=div`
 
+### Range-certificate API
+
+* `rns.certify_signed_bound(max_abs_bound)`
+* `rns.certify_signed_dot_bound(inner_dimension, left_abs_bound, right_abs_bound, addend_abs_bound=0)`
+* `SignedRangeCertificate.unique`
+* `SignedRangeCertificate.headroom`
+* `SignedRangeCertificate.minimum_required_modulus`
+* `SignedRangeCertificate.require_unique()`
+
 ### Scalar-broadcast encoded API
 
 These avoid materializing full constant arrays in Python:
@@ -136,6 +219,7 @@ Auto-dispatch variants:
 ### High-level API
 
 * `rns.Session`
+* `rns.SignedSession`
 * `rns.SessionCache`
 * `rns.EncodedArray`
 
@@ -185,7 +269,9 @@ def make_invertible_divisor(b):
 ## Data model
 
 * input arrays to `encode(...)` are treated as `uint64`
-* values outside `[0, M)` are reduced mod `M` during encode
+* values outside `[0, M)` are reduced mod `M` during unsigned encode
+* `encode_signed(...)` accepts only integers in `[-M/2, M/2 - 1]` and refuses silent wrapping
+* `decode_signed(...)` returns the canonical centered `int64` view
 * rails are returned as:
   * `r0`: `uint16`
   * `r1`: `uint16`
@@ -228,7 +314,8 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 ### Verification status
 
 * correctness sanity checks passed
-* full test suite passed: **50 / 50**
+* the full suite is exercised on Linux, macOS, and Windows across Python 3.10–3.13
+* built wheels are installed and tested before release
 
 ---
 
@@ -287,6 +374,9 @@ import rns_engine as rns
 rns.info()
 
 rns.M
+rns.HALF_M
+rns.SIGNED_MIN
+rns.SIGNED_MAX
 rns.M0
 rns.M1
 rns.M2
@@ -298,9 +388,13 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.4.1
+### v0.5.0
 
-* Maintenance release: repaired packaging metadata, cross-platform wheel builds, and Python 3.10–3.13 CI; arithmetic core unchanged
+* canonical centered signed encoding and decoding
+* strict signed input validation with no silent modular wrapping
+* signed uniqueness certificates using the law `|result| < M/2`
+* exact dot-product and GEMM output-bound receipts
+* `SignedSession` high-level API
 * 4-rail engine (`127 × 8191 × 65536 × 524287`)
 * AVX2-accelerated encoded kernels
 * fused `fma(...)`

{rns_engine-0.4.1 → rns_engine-0.5.0}/pyproject.toml

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

{rns_engine-0.4.1 → rns_engine-0.5.0}/src/rns_engine/__init__.py

@@ -39,6 +39,19 @@ from ._core import (
     omp_num_procs,
 )
 from .engine import EncodedArray, Session, SessionCache
+from .signed import (
+    HALF_M,
+    SIGNED_MAX,
+    SIGNED_MIN,
+    UNIQUE_SIGNED_MAX,
+    UNIQUE_SIGNED_MIN,
+    SignedRangeCertificate,
+    SignedSession,
+    certify_signed_bound,
+    certify_signed_dot_bound,
+    decode_signed,
+    encode_signed,
+)
 
 try:
     __version__ = _distribution_version("rns_engine")
@@ -50,7 +63,9 @@ except PackageNotFoundError:
 __all__ = [
     "HAS_AVX2",
     "M", "M0", "M1", "M2", "M3",
-    "encode", "decode", "op",
+    "HALF_M", "SIGNED_MIN", "SIGNED_MAX",
+    "UNIQUE_SIGNED_MIN", "UNIQUE_SIGNED_MAX",
+    "encode", "decode", "encode_signed", "decode_signed", "op",
     "add", "sub", "mul", "div_", "fma",
     "affine_repeat",
     "mul_u64", "fma_u64", "affine_repeat_u64",
@@ -60,13 +75,17 @@ __all__ = [
     "fma_u64_io", "fma_u64_io_omp", "fma_u64_auto",
     "affine_repeat_u64_io", "affine_repeat_u64_io_omp", "affine_repeat_u64_auto",
     "omp_max_threads", "omp_set_num_threads", "omp_num_procs",
-    "EncodedArray", "SessionCache", "Session",
+    "EncodedArray", "SessionCache", "Session", "SignedSession",
+    "SignedRangeCertificate", "certify_signed_bound", "certify_signed_dot_bound",
     "info",
 ]
 
+
 def info():
     print(f"rns_engine v{__version__}")
     print(f"  Dynamic range : [0, {M:,})")
+    print(f"  Signed view   : [{SIGNED_MIN:,}, {SIGNED_MAX:,}]")
+    print(f"  Unique bound  : |x| < {HALF_M:,}")
     print(f"  Moduli        : {M0} x {M1} x {M2} x {M3}")
     print(f"  AVX2          : {'yes' if HAS_AVX2 else 'no'}")
     print("  Core APIs     : add/sub/mul/fma + raw/omp/auto scalar-broadcast family")

rns_engine-0.5.0/src/rns_engine/signed.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from operator import index
+from typing import Any
+
+import numpy as np
+
+from ._core import M
+from ._core import decode as _decode
+from ._core import encode as _encode
+from .engine import EncodedArray, Session
+
+HALF_M = int(M) // 2
+SIGNED_MIN = -HALF_M
+SIGNED_MAX = HALF_M - 1
+UNIQUE_SIGNED_MIN = -HALF_M + 1
+UNIQUE_SIGNED_MAX = HALF_M - 1
+
+
+def _require_nonnegative_integer(value: Any, *, name: str) -> int:
+    try:
+        integer = index(value)
+    except TypeError as exc:
+        raise TypeError(f"{name} must be an integer") from exc
+    if integer < 0:
+        raise ValueError(f"{name} must be >= 0")
+    return integer
+
+
+def _as_signed_int64_array(x: Any) -> np.ndarray:
+    raw = np.asarray(x)
+    if raw.ndim != 1:
+        raise ValueError("expected a 1D array-like of signed integer values")
+
+    if np.issubdtype(raw.dtype, np.integer):
+        if np.issubdtype(raw.dtype, np.unsignedinteger):
+            if raw.size and np.any(raw > np.uint64(SIGNED_MAX)):
+                raise OverflowError(
+                    f"signed RNS input must be in [{SIGNED_MIN}, {SIGNED_MAX}]"
+                )
+        else:
+            if raw.size and (
+                np.any(raw < np.int64(SIGNED_MIN))
+                or np.any(raw > np.int64(SIGNED_MAX))
+            ):
+                raise OverflowError(
+                    f"signed RNS input must be in [{SIGNED_MIN}, {SIGNED_MAX}]"
+                )
+        return np.ascontiguousarray(raw, dtype=np.int64)
+
+    if raw.dtype == object:
+        values: list[int] = []
+        for position, value in enumerate(raw):
+            try:
+                integer = index(value)
+            except TypeError as exc:
+                raise TypeError(
+                    f"signed RNS input at index {position} is not an integer"
+                ) from exc
+            if integer < SIGNED_MIN or integer > SIGNED_MAX:
+                raise OverflowError(
+                    f"signed RNS input at index {position} must be in "
+                    f"[{SIGNED_MIN}, {SIGNED_MAX}]"
+                )
+            values.append(integer)
+        return np.ascontiguousarray(values, dtype=np.int64)
+
+    raise TypeError("signed RNS input must contain integers")
+
+
+def encode_signed(x: Any) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Encode canonical centered integers without silent modular wrapping.
+
+    Accepted values are in ``[-M/2, M/2 - 1]``. Negative values are mapped to
+    their canonical residues before entering the native four-rail encoder.
+    """
+
+    signed = _as_signed_int64_array(x)
+    residues = signed.copy()
+    negative = residues < 0
+    residues[negative] += int(M)
+    return _encode(np.ascontiguousarray(residues, dtype=np.uint64))
+
+
+def decode_signed(
+    r0: Any,
+    r1: Any,
+    r2: Any,
+    r3: Any,
+) -> np.ndarray:
+    """Decode residues into the canonical centered interval.
+
+    The residue ``M/2`` is represented as ``-M/2``. This is a canonical
+    interpretation, not proof that an unknown mathematical result did not wrap;
+    use :func:`certify_signed_bound` for that guarantee.
+    """
+
+    residues = _decode(r0, r1, r2, r3)
+    centered = np.ascontiguousarray(residues, dtype=np.int64)
+    upper_half = residues >= np.uint64(HALF_M)
+    centered[upper_half] -= int(M)
+    return centered
+
+
+@dataclass(frozen=True, slots=True)
+class SignedRangeCertificate:
+    """Certificate that a known absolute bound has one signed RNS decoding."""
+
+    max_abs_bound: int
+
+    def __post_init__(self) -> None:
+        bound = _require_nonnegative_integer(
+            self.max_abs_bound,
+            name="max_abs_bound",
+        )
+        object.__setattr__(self, "max_abs_bound", bound)
+
+    @property
+    def modulus(self) -> int:
+        return int(M)
+
+    @property
+    def half_modulus(self) -> int:
+        return HALF_M
+
+    @property
+    def unique(self) -> bool:
+        return self.max_abs_bound < HALF_M
+
+    @property
+    def headroom(self) -> int:
+        """Remaining strict signed headroom; negative means the bound exceeds it."""
+
+        return UNIQUE_SIGNED_MAX - self.max_abs_bound
+
+    @property
+    def minimum_required_modulus(self) -> int:
+        """Smallest modulus that uniquely supports ``[-bound, +bound]``."""
+
+        return 2 * self.max_abs_bound + 1
+
+    def require_unique(self) -> SignedRangeCertificate:
+        if not self.unique:
+            raise OverflowError(
+                "signed result is modular-only: the certified absolute bound "
+                f"{self.max_abs_bound} must be less than M/2 ({HALF_M})"
+            )
+        return self
+
+
+def certify_signed_bound(max_abs_bound: int) -> SignedRangeCertificate:
+    """Return a strict uniqueness certificate for a known absolute bound."""
+
+    return SignedRangeCertificate(max_abs_bound=max_abs_bound)
+
+
+def certify_signed_dot_bound(
+    inner_dimension: int,
+    left_abs_bound: int,
+    right_abs_bound: int,
+    addend_abs_bound: int = 0,
+) -> SignedRangeCertificate:
+    """Certify the worst-case magnitude of an exact signed dot product.
+
+    For ``sum(a[k] * b[k]) + c`` with ``inner_dimension`` terms, this uses the
+    conservative exact bound::
+
+        inner_dimension * left_abs_bound * right_abs_bound + addend_abs_bound
+
+    This is also the per-output bound for a GEMM whose entries satisfy the same
+    magnitude limits. The returned certificate is unique only when that bound
+    is strictly less than ``M/2``.
+    """
+
+    k = _require_nonnegative_integer(inner_dimension, name="inner_dimension")
+    left = _require_nonnegative_integer(left_abs_bound, name="left_abs_bound")
+    right = _require_nonnegative_integer(
+        right_abs_bound,
+        name="right_abs_bound",
+    )
+    addend = _require_nonnegative_integer(
+        addend_abs_bound,
+        name="addend_abs_bound",
+    )
+    return certify_signed_bound(k * left * right + addend)
+
+
+class SignedSession(Session):
+    """Session API whose external values use centered signed RNS semantics."""
+
+    def encode_signed(self, x: Any) -> EncodedArray:
+        return EncodedArray(*encode_signed(x))
+
+    def decode_signed(self, x: EncodedArray) -> np.ndarray:
+        return decode_signed(*x.rails())
+
+
+__all__ = [
+    "HALF_M",
+    "SIGNED_MIN",
+    "SIGNED_MAX",
+    "UNIQUE_SIGNED_MIN",
+    "UNIQUE_SIGNED_MAX",
+    "SignedRangeCertificate",
+    "SignedSession",
+    "certify_signed_bound",
+    "certify_signed_dot_bound",
+    "encode_signed",
+    "decode_signed",
+]

{rns_engine-0.4.1 → rns_engine-0.5.0/src/rns_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.4.1
+Version: 0.5.0
 Summary: Exact RNS engine with session/cache API.
 Author: Evan Wesley
 License-Expression: AGPL-3.0-only
@@ -109,12 +109,86 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 
 ---
 
+## Centered signed arithmetic and range certificates
+
+The native core computes exact residues modulo `M`. Version 0.5 adds a canonical signed view over:
+
+```text
+[-M/2, M/2 - 1]
+=
+[-17,871,445,090,598,912, 17,871,445,090,598,911]
+```
+
+```python
+import numpy as np
+import rns_engine as rns
+
+values = np.array([-5, 0, 7], dtype=np.int64)
+rails = rns.encode_signed(values)
+round_trip = rns.decode_signed(*rails)
+
+assert np.array_equal(round_trip, values)
+```
+
+`encode_signed(...)` rejects values outside the centered interval instead of silently wrapping them modulo `M`.
+
+A centered decoding is a canonical interpretation of a residue. It is **not by itself proof that an unknown mathematical result did not wrap**. Unique signed reconstruction requires an independent strict magnitude bound:
+
+```text
+|result| < M/2
+```
+
+Use a range certificate before claiming that a residue is the unique signed integer result:
+
+```python
+certificate = rns.certify_signed_bound(max_abs_bound=1_000_000)
+certificate.require_unique()
+
+print(certificate.headroom)
+print(certificate.minimum_required_modulus)
+```
+
+For a signed dot product or one GEMM output entry, the engine can build the worst-case receipt directly:
+
+```python
+certificate = rns.certify_signed_dot_bound(
+    inner_dimension=5120,
+    left_abs_bound=127,
+    right_abs_bound=127,
+)
+
+assert certificate.max_abs_bound == 82_580_480
+assert certificate.unique
+certificate.require_unique()
+```
+
+This uses the exact conservative law:
+
+```text
+output bound
+=
+inner_dimension × left bound × right bound + addend bound
+```
+
+`SignedSession` exposes the existing residue arithmetic with signed external values:
+
+```python
+s = rns.SignedSession()
+a = s.encode_signed([-5, 7])
+b = s.encode_signed([3, -10])
+out = s.decode_signed(s.add(a, b))
+```
+
+---
+
 ## Core API
 
 ### Encoded rail API
 
 * `rns.encode(x)` → `(r0, r1, r2, r3)`
 * `rns.decode(r0, r1, r2, r3)` → `uint64[]`
+* `rns.encode_signed(x)` → strict centered signed encoding
+* `rns.decode_signed(r0, r1, r2, r3)` → canonical `int64[]`
 * `rns.add(*ea, *eb)`
 * `rns.sub(*ea, *eb)`
 * `rns.mul(*ea, *eb)`
@@ -122,6 +196,15 @@ hot = s.hot_loop_affine(x, multiplier=1_000_003, addend=7, iterations=1000)
 * `rns.fma(*ea, *eb, *ec)`
 * `rns.op(*ea, *eb, code)` where `0=add 1=mul 2=sub 3=div`
 
+### Range-certificate API
+
+* `rns.certify_signed_bound(max_abs_bound)`
+* `rns.certify_signed_dot_bound(inner_dimension, left_abs_bound, right_abs_bound, addend_abs_bound=0)`
+* `SignedRangeCertificate.unique`
+* `SignedRangeCertificate.headroom`
+* `SignedRangeCertificate.minimum_required_modulus`
+* `SignedRangeCertificate.require_unique()`
+
 ### Scalar-broadcast encoded API
 
 These avoid materializing full constant arrays in Python:
@@ -159,6 +242,7 @@ Auto-dispatch variants:
 ### High-level API
 
 * `rns.Session`
+* `rns.SignedSession`
 * `rns.SessionCache`
 * `rns.EncodedArray`
 
@@ -208,7 +292,9 @@ def make_invertible_divisor(b):
 ## Data model
 
 * input arrays to `encode(...)` are treated as `uint64`
-* values outside `[0, M)` are reduced mod `M` during encode
+* values outside `[0, M)` are reduced mod `M` during unsigned encode
+* `encode_signed(...)` accepts only integers in `[-M/2, M/2 - 1]` and refuses silent wrapping
+* `decode_signed(...)` returns the canonical centered `int64` view
 * rails are returned as:
   * `r0`: `uint16`
   * `r1`: `uint16`
@@ -251,7 +337,8 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 ### Verification status
 
 * correctness sanity checks passed
-* full test suite passed: **50 / 50**
+* the full suite is exercised on Linux, macOS, and Windows across Python 3.10–3.13
+* built wheels are installed and tested before release
 
 ---
 
@@ -310,6 +397,9 @@ import rns_engine as rns
 rns.info()
 
 rns.M
+rns.HALF_M
+rns.SIGNED_MIN
+rns.SIGNED_MAX
 rns.M0
 rns.M1
 rns.M2
@@ -321,9 +411,13 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.4.1
+### v0.5.0
 
-* Maintenance release: repaired packaging metadata, cross-platform wheel builds, and Python 3.10–3.13 CI; arithmetic core unchanged
+* canonical centered signed encoding and decoding
+* strict signed input validation with no silent modular wrapping
+* signed uniqueness certificates using the law `|result| < M/2`
+* exact dot-product and GEMM output-bound receipts
+* `SignedSession` high-level API
 * 4-rail engine (`127 × 8191 × 65536 × 524287`)
 * AVX2-accelerated encoded kernels
 * fused `fma(...)`

{rns_engine-0.4.1 → rns_engine-0.5.0}/src/rns_engine.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ setup.py
 src/rns_engine/__init__.py
 src/rns_engine/_core.cpp
 src/rns_engine/engine.py
+src/rns_engine/signed.py
 src/rns_engine.egg-info/PKG-INFO
 src/rns_engine.egg-info/SOURCES.txt
 src/rns_engine.egg-info/dependency_links.txt
@@ -13,4 +14,5 @@ src/rns_engine.egg-info/requires.txt
 src/rns_engine.egg-info/top_level.txt
 tests/test_packaging.py
 tests/test_rns.py
-tests/test_session.py
+tests/test_session.py
+tests/test_signed.py

rns_engine-0.5.0/tests/test_signed.py

@@ -0,0 +1,138 @@
+import numpy as np
+import pytest
+
+import rns_engine as rns
+
+
+def test_signed_constants_match_four_rail_modulus():
+    assert rns.M == 35_742_890_181_197_824
+    assert rns.HALF_M == rns.M // 2
+    assert rns.SIGNED_MIN == -rns.HALF_M
+    assert rns.SIGNED_MAX == rns.HALF_M - 1
+    assert rns.UNIQUE_SIGNED_MIN == -rns.HALF_M + 1
+    assert rns.UNIQUE_SIGNED_MAX == rns.HALF_M - 1
+
+
+def test_signed_round_trip_including_canonical_boundaries():
+    values = np.array(
+        [rns.SIGNED_MIN, -1_000_003, -1, 0, 1, 1_000_003, rns.SIGNED_MAX],
+        dtype=np.int64,
+    )
+
+    decoded = rns.decode_signed(*rns.encode_signed(values))
+
+    np.testing.assert_array_equal(decoded, values)
+    assert decoded.dtype == np.int64
+
+
+def test_negative_one_uses_the_same_residue_as_m_minus_one():
+    signed_rails = rns.encode_signed(np.array([-1], dtype=np.int64))
+    unsigned_rails = rns.encode(np.array([rns.M - 1], dtype=np.uint64))
+
+    for signed_rail, unsigned_rail in zip(signed_rails, unsigned_rails):
+        np.testing.assert_array_equal(signed_rail, unsigned_rail)
+
+
+def test_half_modulus_residue_has_canonical_negative_interpretation():
+    rails = rns.encode(np.array([rns.HALF_M], dtype=np.uint64))
+
+    decoded = rns.decode_signed(*rails)
+
+    np.testing.assert_array_equal(decoded, np.array([rns.SIGNED_MIN], dtype=np.int64))
+
+
+def test_signed_encoder_refuses_silent_wraparound():
+    with pytest.raises(OverflowError, match="signed RNS input"):
+        rns.encode_signed([rns.SIGNED_MIN - 1])
+
+    with pytest.raises(OverflowError, match="signed RNS input"):
+        rns.encode_signed([rns.SIGNED_MAX + 1])
+
+
+def test_signed_encoder_rejects_non_integer_and_non_vector_input():
+    with pytest.raises(TypeError, match="must contain integers"):
+        rns.encode_signed([1.5, 2.5])
+
+    with pytest.raises(ValueError, match="1D"):
+        rns.encode_signed([[1, 2], [3, 4]])
+
+
+def test_signed_session_uses_existing_residue_arithmetic():
+    session = rns.SignedSession()
+    a = session.encode_signed([-5, 7])
+    b = session.encode_signed([3, -10])
+
+    np.testing.assert_array_equal(
+        session.decode_signed(session.add(a, b)),
+        np.array([-2, -3], dtype=np.int64),
+    )
+    np.testing.assert_array_equal(
+        session.decode_signed(session.mul(a, b)),
+        np.array([-15, -70], dtype=np.int64),
+    )
+
+
+def test_strict_signed_bound_certificate():
+    safe = rns.certify_signed_bound(rns.HALF_M - 1)
+    assert safe.unique is True
+    assert safe.headroom == 0
+    assert safe.minimum_required_modulus == rns.M - 1
+    assert safe.require_unique() is safe
+
+    ambiguous = rns.certify_signed_bound(rns.HALF_M)
+    assert ambiguous.unique is False
+    assert ambiguous.headroom == -1
+    assert ambiguous.minimum_required_modulus == rns.M + 1
+    with pytest.raises(OverflowError, match="modular-only"):
+        ambiguous.require_unique()
+
+
+def test_signed_bound_certificate_validates_the_bound():
+    with pytest.raises(ValueError, match=">= 0"):
+        rns.certify_signed_bound(-1)
+
+    with pytest.raises(TypeError, match="must be an integer"):
+        rns.certify_signed_bound(1.5)
+
+
+def test_warpfrac_int8_dot_bound_is_uniquely_signed():
+    certificate = rns.certify_signed_dot_bound(
+        inner_dimension=5120,
+        left_abs_bound=127,
+        right_abs_bound=127,
+    )
+
+    assert certificate.max_abs_bound == 82_580_480
+    assert certificate.unique is True
+    assert certificate.headroom == rns.UNIQUE_SIGNED_MAX - 82_580_480
+    assert certificate.require_unique() is certificate
+
+
+def test_dot_bound_accounts_for_an_existing_addend():
+    certificate = rns.certify_signed_dot_bound(3, 5, 7, addend_abs_bound=11)
+
+    assert certificate.max_abs_bound == 116
+    assert certificate.minimum_required_modulus == 233
+
+
+def test_dot_bound_exposes_modular_only_outputs():
+    certificate = rns.certify_signed_dot_bound(rns.HALF_M, 1, 1)
+
+    assert certificate.max_abs_bound == rns.HALF_M
+    assert certificate.unique is False
+    with pytest.raises(OverflowError, match="modular-only"):
+        certificate.require_unique()
+
+
+def test_dot_bound_validates_each_input():
+    with pytest.raises(ValueError, match="inner_dimension"):
+        rns.certify_signed_dot_bound(-1, 1, 1)
+
+    with pytest.raises(TypeError, match="left_abs_bound"):
+        rns.certify_signed_dot_bound(1, 1.5, 1)
+
+    with pytest.raises(ValueError, match="right_abs_bound"):
+        rns.certify_signed_dot_bound(1, 1, -1)
+
+    with pytest.raises(TypeError, match="addend_abs_bound"):
+        rns.certify_signed_dot_bound(1, 1, 1, addend_abs_bound="7")