Clarify Gaussian polynomial term ordering

Author: Grace Lee Rui Yue

src/jacobian/contracts/probability.py

@@ -127,6 +127,10 @@ class GaussianPolynomial(ContractModel):
     terms: tuple[GaussianPolynomialTerm, ...] = Field(
         min_length=1,
         max_length=MAX_GAUSSIAN_POLYNOMIAL_TERMS,
+        description=(
+            "Nonzero sparse terms ordered lexicographically by their complete "
+            "exponent vectors, for example [0, 1] before [1, 0]."
+        ),
     )
 
     @model_validator(mode="after")
@@ -136,10 +140,13 @@ def require_canonical_sparse_polynomial(self) -> Self:
             raise ValueError(
                 "every Gaussian polynomial exponent vector must match variable_count"
             )
-        if any(left >= right for left, right in pairwise(exponents)):
-            raise ValueError(
-                "Gaussian polynomial terms must use strictly increasing exponent order"
-            )
+        for left, right in pairwise(exponents):
+            if left >= right:
+                raise ValueError(
+                    "Gaussian polynomial terms must use strictly increasing "
+                    "lexicographic exponent-vector order; first offending adjacent "
+                    f"pair is {list(left)} then {list(right)}"
+                )
         return self
 
 

tests/domain/probability/test_finite_probability.py

@@ -349,6 +349,34 @@ def test_multivariate_gaussian_polynomial_moment_uses_independence(
     assert result.output["result"]["expanded_monomial_count"] == 5
 
 
+def test_gaussian_polynomial_rejects_nonlexicographic_terms_with_recovery_detail(
+    domain_services: DomainTestServices,
+) -> None:
+    result = domain_services.core.capabilities.invoke(
+        CapabilityRequest(
+            capability_id="probability.gaussian_polynomial.moment.compute",
+            input={
+                "polynomial": {
+                    "variable_count": 2,
+                    "terms": [
+                        {"coefficient": _complex(1), "exponents": [1, 0]},
+                        {"coefficient": _complex(1), "exponents": [0, 1]},
+                    ],
+                },
+                "order": 2,
+            },
+        )
+    )
+
+    assert result.execution.status is ExecutionStatus.ERROR
+    diagnostic = result.diagnostics[0]
+    assert diagnostic.code == "INVALID_FINITE_PROBABILITY_REQUEST"
+    assert diagnostic.hint is not None
+    assert "lexicographic exponent-vector order" in diagnostic.hint
+    assert "[1, 0] then [0, 1]" in diagnostic.hint
+    assert result.artifact_uris == ()
+
+
 def test_gaussian_polynomial_zero_order_is_the_constant_one(
     domain_services: DomainTestServices,
 ) -> None: