Merge branch 'codex/public-math-contracts' into codex/singular-ideal-operations

Author: morluto

src/jacobian/math/matrices/symbolic/_models.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from itertools import combinations, permutations
 from typing import Literal, Self
 
 from pydantic import Field, model_validator
@@ -12,6 +13,87 @@
 MAX_SYMBOLIC_MATRIX_DIMENSION = 8
 MAX_SYMBOLIC_VARIABLES = 8
 MAX_SYMBOLIC_MATRIX_TERMS = 512
+MAX_SYMBOLIC_RESULT_TERMS = 256
+MAX_SYMBOLIC_RESULT_EXPONENT = 64
+MAX_SYMBOLIC_RESULT_COEFFICIENT_DIGITS = 128
+
+
+def _is_polynomial_entry(value: RationalFunction) -> bool:
+    terms = value.denominator.terms
+    return (
+        len(terms) == 1
+        and terms[0].coefficient.num == "1"
+        and terms[0].coefficient.den == "1"
+        and all(exponent == 0 for exponent in terms[0].exponents)
+    )
+
+
+def _principal_minor_term_bounds(
+    entries: tuple[tuple[RationalFunction, ...], ...],
+) -> tuple[int, ...]:
+    """Bound raw terms in each characteristic coefficient by Leibniz expansion."""
+
+    dimension = len(entries)
+    bounds = [1]
+    for size in range(1, dimension + 1):
+        coefficient_terms = 0
+        for axes in combinations(range(dimension), size):
+            for columns in permutations(axes):
+                product_terms = 1
+                for row, column in zip(axes, columns, strict=True):
+                    product_terms *= len(entries[row][column].numerator.terms)
+                coefficient_terms += product_terms
+        bounds.append(coefficient_terms)
+    return tuple(bounds)
+
+
+def _require_determinant_family_result_budget(
+    matrix: SymbolicMatrix,
+    *,
+    characteristic_polynomial: bool,
+) -> None:
+    dimension = len(matrix.entries)
+    if dimension == 1:
+        return
+    values = tuple(value for row in matrix.entries for value in row)
+    if any(not _is_polynomial_entry(value) for value in values):
+        raise ValueError(
+            "multi-dimensional determinant-family requests require polynomial entries"
+        )
+    term_bounds = _principal_minor_term_bounds(matrix.entries)
+    relevant_bounds = term_bounds[1:] if characteristic_polynomial else term_bounds[-1:]
+    if any(bound > MAX_SYMBOLIC_RESULT_TERMS for bound in relevant_bounds):
+        raise ValueError("determinant-family expansion exceeds the result term budget")
+    maximum_exponent = max(
+        (
+            exponent
+            for value in values
+            for term in value.numerator.terms
+            for exponent in term.exponents
+        ),
+        default=0,
+    )
+    if dimension * maximum_exponent > MAX_SYMBOLIC_RESULT_EXPONENT:
+        raise ValueError(
+            "determinant-family expansion exceeds the result exponent budget"
+        )
+    coefficient_digits = max(
+        (
+            len(component.lstrip("-"))
+            for value in values
+            for term in value.numerator.terms
+            for component in (term.coefficient.num, term.coefficient.den)
+        ),
+        default=1,
+    )
+    if any(
+        bound * dimension * coefficient_digits + len(str(max(bound, 1)))
+        > MAX_SYMBOLIC_RESULT_COEFFICIENT_DIGITS
+        for bound in relevant_bounds
+    ):
+        raise ValueError(
+            "determinant-family expansion exceeds the result coefficient budget"
+        )
 
 
 class SymbolicMatrix(StrictModel):
@@ -92,28 +174,41 @@ def require_square(self) -> Self:
 class SymbolicDeterminantRequest(SquareSymbolicMatrixRequest):
     """A square matrix whose exact determinant fits the public result type."""
 
+    matrix: SymbolicMatrix = Field(
+        description=(
+            "A square symbolic matrix. One-dimensional matrices may contain any "
+            "accepted rational function; larger matrices require polynomial "
+            "entries whose derived determinant expansion has at most 256 terms, "
+            "exponent 64, and 128-digit coefficient components."
+        )
+    )
+
     @model_validator(mode="after")
     def require_representable_determinant(self) -> Self:
-        # The input sparsity budget bounds backend work, but rational-function
-        # expansion can still exceed the canonical result representation.  Run
-        # the bounded exact kernel at admission so an accepted request cannot
-        # fail later while constructing its typed result.
-        from jacobian.math.matrices.symbolic import symbolic_determinant
-
-        symbolic_determinant(self.matrix.entries, self.matrix.variables)
+        _require_determinant_family_result_budget(
+            self.matrix,
+            characteristic_polynomial=False,
+        )
         return self
 
 
 class SymbolicCharacteristicPolynomialRequest(SquareSymbolicMatrixRequest):
     """A square matrix whose characteristic polynomial fits the result type."""
 
+    matrix: SymbolicMatrix = Field(
+        description=(
+            "A square symbolic matrix. One-dimensional matrices may contain any "
+            "accepted rational function; larger matrices require polynomial "
+            "entries whose derived principal-minor expansions each have at most "
+            "256 terms, exponent 64, and 128-digit coefficient components."
+        )
+    )
+
     @model_validator(mode="after")
     def require_representable_characteristic_polynomial(self) -> Self:
-        from jacobian.math.matrices.symbolic import symbolic_characteristic_polynomial
-
-        symbolic_characteristic_polynomial(
-            self.matrix.entries,
-            self.matrix.variables,
+        _require_determinant_family_result_budget(
+            self.matrix,
+            characteristic_polynomial=True,
         )
         return self
 

src/jacobian/math/projective_coords_ops/_models.py

@@ -6,10 +6,24 @@
 
 from pydantic import Field, model_validator
 
-from jacobian._exact import CanonicalRational
+from jacobian._exact import MAX_CANONICAL_RATIONAL_DIGITS, CanonicalRational
 from jacobian._models import StrictModel
 
 MAX_DIM = 16
+MAX_PROJECTIVE_COORDINATE_DIGITS = MAX_CANONICAL_RATIONAL_DIGITS // 2
+
+
+def _require_ratio_result_budget(
+    coordinates: tuple[CanonicalRational, ...],
+) -> None:
+    if any(
+        len(component.lstrip("-")) > MAX_PROJECTIVE_COORDINATE_DIGITS
+        for coordinate in coordinates
+        for component in (coordinate.num, coordinate.den)
+    ):
+        raise ValueError(
+            "projective coordinate components exceed the 16,384-digit ratio budget"
+        )
 
 
 class RationalProjectivePoint(StrictModel):
@@ -30,11 +44,17 @@ def require_not_all_zero(self) -> Self:
 
 class RationalPointConstructRequest(StrictModel):
     coordinates: tuple[CanonicalRational, ...] = Field(
-        min_length=1, max_length=MAX_DIM + 1
+        min_length=1,
+        max_length=MAX_DIM + 1,
+        description=(
+            "Homogeneous coordinates whose rational components are at most "
+            "16,384 digits so every normalization ratio remains representable."
+        ),
     )
 
     @model_validator(mode="after")
     def require_valid(self) -> Self:
+        _require_ratio_result_budget(self.coordinates)
         if all(c.as_fraction() == 0 for c in self.coordinates):
             raise ValueError(
                 "projective point must have at least one nonzero coordinate"
@@ -43,11 +63,17 @@ def require_valid(self) -> Self:
 
 
 class StandardChartRequest(StrictModel):
-    point: RationalProjectivePoint
+    point: RationalProjectivePoint = Field(
+        description=(
+            "A rational projective point whose coordinate components are at most "
+            "16,384 digits so every chart ratio remains representable."
+        )
+    )
     chart_index: int = Field(ge=0)
 
     @model_validator(mode="after")
     def require_valid(self) -> Self:
+        _require_ratio_result_budget(self.point.coordinates)
         if self.chart_index >= len(self.point.coordinates):
             raise ValueError("chart_index out of range")
         if self.point.coordinates[self.chart_index].as_fraction() == 0:
@@ -56,12 +82,18 @@ def require_valid(self) -> Self:
 
 
 class ChartTransitionRequest(StrictModel):
-    point: RationalProjectivePoint
+    point: RationalProjectivePoint = Field(
+        description=(
+            "A rational projective point whose coordinate components are at most "
+            "16,384 digits so every target-chart ratio remains representable."
+        )
+    )
     chart_i: int = Field(ge=0)
     chart_j: int = Field(ge=0)
 
     @model_validator(mode="after")
     def require_valid(self) -> Self:
+        _require_ratio_result_budget(self.point.coordinates)
         n = len(self.point.coordinates)
         if self.chart_i >= n or self.chart_j >= n:
             raise ValueError("chart index out of range")

tests/math/matrices/test_symbolic_matrix.py

@@ -148,12 +148,25 @@ def test_determinant_request_rejects_unrepresentable_expansion() -> None:
         for row in range(8)
     )
 
-    with pytest.raises(ValidationError, match="term operation budget"):
+    with pytest.raises(ValidationError, match="result term budget"):
         SymbolicDeterminantRequest(
             matrix=SymbolicMatrix(variables=variables, entries=entries)
         )
 
 
+def test_determinant_request_admission_does_not_execute_kernel(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import jacobian.math.matrices.symbolic as symbolic
+
+    def fail_if_called(*_args: object, **_kwargs: object) -> None:
+        raise AssertionError("determinant kernel ran during request validation")
+
+    monkeypatch.setattr(symbolic, "symbolic_determinant", fail_if_called)
+
+    assert isinstance(_generic_two_by_two(), SymbolicDeterminantRequest)
+
+
 def test_symbolic_rank_of_full_and_singular_matrices() -> None:
     full = compute_symbolic_rank(_generic_two_by_two())
     assert isinstance(full, SymbolicRankResult)

tests/math/projective_coords_ops/test_projective_coords.py

@@ -100,6 +100,22 @@ def test_chart_transition_reports_outside_target_chart() -> None:
     assert result.transition is None
 
 
+def test_chart_transition_rejects_unrepresentable_ratio_growth() -> None:
+    component = "1" + "0" * 16_384
+
+    with pytest.raises(ValidationError, match="ratio budget"):
+        ChartTransitionRequest(
+            point=RationalProjectivePoint(
+                coordinates=(
+                    CanonicalRational(num=component, den="1"),
+                    CanonicalRational(num="1", den=component),
+                )
+            ),
+            chart_i=0,
+            chart_j=1,
+        )
+
+
 def test_chart_transition_round_trips_between_defined_charts() -> None:
     point = _point(_r("2"), _r("3"), _r("5"))
     forward = compute_chart_transition(