fix(contracts): define identifier and opaque label types

Author: morluto

src/jacobian/math/_labels.py

@@ -0,0 +1,37 @@
+"""Shared passive value types for opaque mathematical labels."""
+
+from __future__ import annotations
+
+import unicodedata
+from typing import Annotated
+
+from pydantic import AfterValidator, Field, StringConstraints
+
+MAX_OPAQUE_LABEL_LENGTH = 64
+
+
+def _require_opaque_label(value: str) -> str:
+    if value != value.strip():
+        raise ValueError("label must not have leading or trailing whitespace")
+    if any(unicodedata.category(character) == "Cc" for character in value):
+        raise ValueError("label must not contain control characters")
+    return value
+
+
+OpaqueLabel = Annotated[
+    str,
+    StringConstraints(
+        min_length=1,
+        max_length=MAX_OPAQUE_LABEL_LENGTH,
+        strict=True,
+    ),
+    Field(
+        description=(
+            "Opaque mathematical label without leading/trailing whitespace or "
+            "Unicode control characters."
+        )
+    ),
+    AfterValidator(_require_opaque_label),
+]
+
+__all__ = ["MAX_OPAQUE_LABEL_LENGTH", "OpaqueLabel"]

src/jacobian/math/finite_categories/_models.py

@@ -7,6 +7,7 @@
 from pydantic import Field, model_validator
 
 from jacobian._models import StrictModel
+from jacobian.math._labels import OpaqueLabel
 
 MAX_OBJECTS = 20
 MAX_MORPHISMS = 100
@@ -16,9 +17,9 @@
 class MorphismSpec(StrictModel):
     """One morphism: source and target objects, plus a unique ID."""
 
-    morphism_id: str
-    source: str
-    target: str
+    morphism_id: OpaqueLabel
+    source: OpaqueLabel
+    target: OpaqueLabel
 
 
 def _morphism_index(
@@ -152,10 +153,14 @@ class FiniteCategoryRequest(StrictModel):
     laws are enforced once at the value boundary.
     """
 
-    objects: tuple[str, ...] = Field(min_length=1, max_length=MAX_OBJECTS)
+    objects: tuple[OpaqueLabel, ...] = Field(min_length=1, max_length=MAX_OBJECTS)
     morphisms: tuple[MorphismSpec, ...] = Field(max_length=MAX_MORPHISMS)
-    identities: tuple[tuple[str, str], ...] = Field(max_length=MAX_OBJECTS)
-    composition: tuple[tuple[str, str, str], ...] = Field(max_length=MAX_COMPOSITIONS)
+    identities: tuple[tuple[OpaqueLabel, OpaqueLabel], ...] = Field(
+        max_length=MAX_OBJECTS
+    )
+    composition: tuple[tuple[OpaqueLabel, OpaqueLabel, OpaqueLabel], ...] = Field(
+        max_length=MAX_COMPOSITIONS
+    )
 
     @model_validator(mode="after")
     def require_valid_category(self) -> Self:
@@ -166,21 +171,21 @@ def require_valid_category(self) -> Self:
 class CategoryProfileResult(StrictModel):
     """Profile of a finite category: hom-sets, endomorphisms, identities."""
 
-    objects: tuple[str, ...]
+    objects: tuple[OpaqueLabel, ...]
     num_objects: int
     num_morphisms: int
-    hom_sets: tuple[tuple[str, str, int], ...]
-    endomorphisms: tuple[tuple[str, int], ...]
-    identity_morphisms: tuple[tuple[str, str], ...]
+    hom_sets: tuple[tuple[OpaqueLabel, OpaqueLabel, int], ...]
+    endomorphisms: tuple[tuple[OpaqueLabel, int], ...]
+    identity_morphisms: tuple[tuple[OpaqueLabel, OpaqueLabel], ...]
 
 
 class OppositeCategoryResult(StrictModel):
     """The opposite category: reversed morphisms and reversed composition."""
 
-    objects: tuple[str, ...]
+    objects: tuple[OpaqueLabel, ...]
     morphisms: tuple[MorphismSpec, ...]
-    identities: tuple[tuple[str, str], ...]
-    composition: tuple[tuple[str, str, str], ...]
+    identities: tuple[tuple[OpaqueLabel, OpaqueLabel], ...]
+    composition: tuple[tuple[OpaqueLabel, OpaqueLabel, OpaqueLabel], ...]
 
     @model_validator(mode="after")
     def require_valid_opposite(self) -> Self:

src/jacobian/math/finite_semigroups/_models.py

@@ -7,25 +7,22 @@
 from pydantic import Field, model_validator
 
 from jacobian._models import StrictModel
+from jacobian.math._labels import OpaqueLabel
 
 MAX_ELEMENTS = 50
-MAX_LABEL_LENGTH = 64
 
 
 class FiniteSemigroup(StrictModel):
     """A finite semigroup: a finite set with an associative binary operation."""
 
-    elements: tuple[str, ...] = Field(min_length=1, max_length=MAX_ELEMENTS)
-    multiplication: tuple[tuple[str, ...], ...]
+    elements: tuple[OpaqueLabel, ...] = Field(min_length=1, max_length=MAX_ELEMENTS)
+    multiplication: tuple[tuple[OpaqueLabel, ...], ...]
 
     @model_validator(mode="after")
     def require_valid_semigroup(self) -> Self:
         labels = set(self.elements)
         if len(labels) != len(self.elements):
             raise ValueError("element labels must be distinct")
-        for label in self.elements:
-            if len(label) > MAX_LABEL_LENGTH:
-                raise ValueError("element label exceeds the bounded length budget")
         if len(self.multiplication) != len(self.elements):
             raise ValueError("multiplication table must have one row per element")
         for row in self.multiplication:
@@ -59,7 +56,7 @@ class PowerProfileRequest(StrictModel):
     """Request the power profile of one element in a finite semigroup."""
 
     semigroup: FiniteSemigroup
-    element: str
+    element: OpaqueLabel
 
     @model_validator(mode="after")
     def require_element_exists(self) -> Self:
@@ -79,12 +76,12 @@ class PowerProfileResult(StrictModel):
     """
 
     semigroup: FiniteSemigroup
-    element: str
-    powers: tuple[str, ...]
+    element: OpaqueLabel
+    powers: tuple[OpaqueLabel, ...]
     index: int = Field(ge=1)
     period: int = Field(ge=1)
-    idempotent: str
-    cyclic_subsemigroup: tuple[str, ...]
+    idempotent: OpaqueLabel
+    cyclic_subsemigroup: tuple[OpaqueLabel, ...]
 
     @model_validator(mode="after")
     def bind_power_profile(self) -> Self:
@@ -114,7 +111,7 @@ class GeneratedSubsemigroupRequest(StrictModel):
     """Request the subsemigroup generated by a set of elements."""
 
     semigroup: FiniteSemigroup
-    generators: tuple[str, ...] = Field(min_length=1)
+    generators: tuple[OpaqueLabel, ...] = Field(min_length=1)
 
     @model_validator(mode="after")
     def require_generators_exist(self) -> Self:
@@ -128,15 +125,15 @@ def require_generators_exist(self) -> Self:
 class GeneratedSubsemigroupResult(StrictModel):
     """The subsemigroup generated by a set of elements."""
 
-    generators: tuple[str, ...]
-    elements: tuple[str, ...]
+    generators: tuple[OpaqueLabel, ...]
+    elements: tuple[OpaqueLabel, ...]
 
 
 class ElementPowerRequest(StrictModel):
     """Request the exact power ``element^exponent`` in a finite semigroup."""
 
     semigroup: FiniteSemigroup
-    element: str
+    element: OpaqueLabel
     exponent: int = Field(ge=1)
 
     @model_validator(mode="after")
@@ -150,9 +147,9 @@ class ElementPowerResult(StrictModel):
     """The exact power ``element^exponent`` in a finite semigroup."""
 
     semigroup: FiniteSemigroup
-    element: str
+    element: OpaqueLabel
     exponent: int = Field(ge=1)
-    power: str
+    power: OpaqueLabel
 
     @model_validator(mode="after")
     def bind_power(self) -> Self:
@@ -179,7 +176,7 @@ class IdempotentsResult(StrictModel):
     """All idempotent elements of a finite semigroup."""
 
     semigroup: FiniteSemigroup
-    idempotents: tuple[str, ...]
+    idempotents: tuple[OpaqueLabel, ...]
 
     @model_validator(mode="after")
     def bind_idempotents(self) -> Self:
@@ -197,7 +194,7 @@ class PrincipalIdealsRequest(StrictModel):
     """Request the principal ideal of each listed element."""
 
     semigroup: FiniteSemigroup
-    elements: tuple[str, ...] = Field(min_length=1, max_length=MAX_ELEMENTS)
+    elements: tuple[OpaqueLabel, ...] = Field(min_length=1, max_length=MAX_ELEMENTS)
 
     @model_validator(mode="after")
     def require_elements_exist(self) -> Self:
@@ -222,8 +219,8 @@ class PrincipalIdealsResult(StrictModel):
     """
 
     semigroup: FiniteSemigroup
-    elements: tuple[str, ...]
-    ideals: tuple[tuple[str, ...], ...]
+    elements: tuple[OpaqueLabel, ...]
+    ideals: tuple[tuple[OpaqueLabel, ...], ...]
 
     @model_validator(mode="after")
     def bind_ideals(self) -> Self:

src/jacobian/math/finite_topology_spaces/_models.py

@@ -7,6 +7,7 @@
 from pydantic import Field, model_validator
 
 from jacobian._models import StrictModel
+from jacobian.math._labels import OpaqueLabel
 from jacobian.math.finite_topology_spaces.values import (
     FiniteTopologicalMap,
     FiniteTopologicalSpace,
@@ -55,7 +56,7 @@ class KolmogorovQuotientRequest(StrictModel):
 
 
 class KolmogorovQuotientResult(StrictModel):
-    quotient_points: tuple[str, ...]
+    quotient_points: tuple[OpaqueLabel, ...]
     quotient_preorder: tuple[tuple[int, ...], ...]
 
 

src/jacobian/math/finite_topology_spaces/values.py

@@ -7,10 +7,16 @@
 from pydantic import Field, model_validator
 
 from jacobian._models import StrictModel
+from jacobian.math._labels import OpaqueLabel
 
 MAX_POINTS = 64
 
 
+def _require_distinct_points(points: tuple[str, ...]) -> None:
+    if len(set(points)) != len(points):
+        raise ValueError("point labels must be distinct")
+
+
 class FiniteTopologicalSpace(StrictModel):
     """An immutable finite topological space represented by its specialization
     preorder.
@@ -24,11 +30,12 @@ class FiniteTopologicalSpace(StrictModel):
     point.
     """
 
-    points: tuple[str, ...] = Field(min_length=1, max_length=MAX_POINTS)
+    points: tuple[OpaqueLabel, ...] = Field(min_length=1, max_length=MAX_POINTS)
     preorder: tuple[tuple[int, ...], ...] = Field(min_length=1)
 
     @model_validator(mode="after")
     def require_well_formed(self) -> Self:
+        _require_distinct_points(self.points)
         if len(self.preorder) != len(self.points):
             raise ValueError("preorder must have one row per point")
         for row in self.preorder:

src/jacobian/math/impartial_games/values.py

@@ -8,10 +8,11 @@
 from pydantic import Field, model_validator
 
 from jacobian._models import StrictModel
+from jacobian.math._labels import MAX_OPAQUE_LABEL_LENGTH, OpaqueLabel
 
 MAX_POSITIONS = 500
 MAX_MOVES = 2_000
-MAX_LABEL_LENGTH = 64
+MAX_LABEL_LENGTH = MAX_OPAQUE_LABEL_LENGTH
 MAX_HEAPS = 50
 MAX_HEAP_SIZE = 10_000
 MAX_NIM_OPTIONS = 5_000
@@ -21,14 +22,14 @@
 
 
 class GameMove(StrictModel):
-    source: str = Field(min_length=1, max_length=MAX_LABEL_LENGTH)
-    target: str = Field(min_length=1, max_length=MAX_LABEL_LENGTH)
+    source: OpaqueLabel
+    target: OpaqueLabel
 
 
 class ImpartialGame(StrictModel):
     """A complete finite normal-play impartial game DAG."""
 
-    positions: tuple[str, ...] = Field(min_length=1, max_length=MAX_POSITIONS)
+    positions: tuple[OpaqueLabel, ...] = Field(min_length=1, max_length=MAX_POSITIONS)
     moves: tuple[GameMove, ...] = Field(max_length=MAX_MOVES)
 
     @model_validator(mode="after")

src/jacobian/math/multiple_testing/_models.py

@@ -8,14 +8,15 @@
 
 from jacobian._exact import CanonicalRational
 from jacobian._models import StrictModel
+from jacobian.math._labels import OpaqueLabel
 
 MAX_HYPOTHESES = 1000
 
 
 class HypothesisSpec(StrictModel):
     """One labelled p-value."""
 
-    hypothesis_id: str = Field(min_length=1, max_length=64)
+    hypothesis_id: OpaqueLabel
     p_value: CanonicalRational
 
     @model_validator(mode="after")
@@ -50,15 +51,15 @@ class BHStepUpResult(StrictModel):
 
     critical_index: int = Field(ge=0)
     cutoff_threshold: str
-    rejected: tuple[str, ...]
+    rejected: tuple[OpaqueLabel, ...]
     total_hypotheses: int = Field(ge=1)
 
 
 class FDPRequest(StrictModel):
     """False discovery proportion computation."""
 
-    rejected_ids: tuple[str, ...] = Field(default=())
-    true_null_ids: tuple[str, ...] = Field(default=())
+    rejected_ids: tuple[OpaqueLabel, ...] = Field(default=())
+    true_null_ids: tuple[OpaqueLabel, ...] = Field(default=())
 
 
 class FDPResult(StrictModel):

src/jacobian/math/number_field/_models.py

@@ -8,13 +8,14 @@
 
 from jacobian._models import StrictModel
 from jacobian.canonical import parse_canonical_integer
+from jacobian.math.polynomials.values import PolynomialVariable
 
 
 class NumberFieldRequest(StrictModel):
     """A number field Q(alpha) defined by a minimal polynomial."""
 
     coefficients_descending: tuple[str, ...] = Field(min_length=2, max_length=32)
-    variable: str = Field(min_length=1, max_length=10)
+    variable: PolynomialVariable
 
     @model_validator(mode="after")
     def require_monic_irreducible_integer_polynomial(self) -> Self:

tests/integration/algebra/test_exact_operations.py

@@ -144,6 +144,20 @@ def test_number_field_discriminant_is_not_power_basis_discriminant() -> None:
     assert result.discriminant == "5"
 
 
+@pytest.mark.parametrize(
+    "variable",
+    ["", " ", "x y", "x; y", "x\n", "x\x00", "1x", "x" * 33],
+)
+def test_number_field_variable_uses_polynomial_identifier_grammar(
+    variable: str,
+) -> None:
+    with pytest.raises(ValidationError):
+        NumberFieldRequest(
+            coefficients_descending=("1", "0", "-2"),
+            variable=variable,
+        )
+
+
 def test_integral_basis_is_computed_in_the_defining_power_basis() -> None:
     assert ring_of_integers(["1", "0", "-5"], "x") == ["1", "x/2 + 1/2"]