feat: add incidence structure operations (#1732) (#2114)

* feat(math): add integral binary quadratic forms domain with check, evaluate, reduce, equivalence, and class enumeration

Implement the primitive positive-definite integral binary quadratic form
domain (issue #1830) with five exact operations:

- number_theory.binary_quadratic_form.check: validate coefficients as a
  primitive positive-definite form with negative discriminant D ≡ 0 or 1
  (mod 4), returning the discriminant and symmetric Gram matrix
- number_theory.binary_quadratic_form.evaluate: exact evaluation
  Q(x,y) = a*x^2 + b*x*y + c*y^2 with primitive-pair status
- number_theory.binary_quadratic_form.reduce: Gauss reduction to canonical
  reduced form with SL_2(Z) witness matrix and step ledger
- number_theory.binary_quadratic_form.proper_equivalence.decide: decide
  proper equivalence by comparing canonical reduced representatives,
  returning the exact SL_2(Z) transformation witness
- number_theory.binary_quadratic_form.reduced_classes.compute: enumerate
  all reduced primitive positive-definite classes of a given discriminant,
  returning the complete class set and class number h(D)

Each result model re-runs the native kernel to verify exactness
(fail-closed binding). All 22 known-answer, boundary, and adversarial
tests pass.

* Add request/result models for incidence structure operations

Add Pydantic models for containment profiles, intersections, dual, complement, restriction, derived/residual, Levi graph, and Gram matrix operations. These complement the existing incidence matrix and degree profile models.

* Add incidence structure operations and register tools

Implement pure computation functions for containment profiles (t-subset codegrees), block intersections, dual, complement, restriction, derived/residual, Levi graph, and Gram matrix. Register all 10 MathTool declarations and admission decisions in the catalog.

* Add tests for incidence structure operations

Add tests covering all 10 operations: matrix, degree profile, containment profiles (t=1,2 on triangle and Fano plane), intersections, dual (including double-dual), complement (with size identity), restriction, derived/residual, Levi graph (with label collision), and Gram matrices (point and block axes). All 26 tests pass.

* fix(math): lint and review fixes

* style: ruff format

* fix: mypy and boundary validation

Author: morluto

src/jacobian/math/incidence_structures/_admission.py

@@ -18,6 +18,46 @@
         AdmissionDecision.KEEP,
         "per-point and per-block degree profiles with total incidence count",
     ),
+    OperationAdmission(
+        "incidence.containment_profiles.compute",
+        AdmissionDecision.KEEP,
+        "t-subset containment multiplicity profiles with histogram",
+    ),
+    OperationAdmission(
+        "incidence.intersections.compute",
+        AdmissionDecision.KEEP,
+        "block pairwise intersection subsets and size histogram",
+    ),
+    OperationAdmission(
+        "incidence.dual.compute",
+        AdmissionDecision.KEEP,
+        "dual incidence structure swapping points and block IDs",
+    ),
+    OperationAdmission(
+        "incidence.complement.compute",
+        AdmissionDecision.KEEP,
+        "block complement incidence structure preserving block IDs",
+    ),
+    OperationAdmission(
+        "incidence.restriction.compute",
+        AdmissionDecision.KEEP,
+        "point/block restriction preserving block IDs",
+    ),
+    OperationAdmission(
+        "incidence.derived_residual.compute",
+        AdmissionDecision.KEEP,
+        "derived and residual incidence structures at a point",
+    ),
+    OperationAdmission(
+        "incidence.levi_graph.compute",
+        AdmissionDecision.KEEP,
+        "labelled bipartite Levi incidence graph",
+    ),
+    OperationAdmission(
+        "incidence.gram.compute",
+        AdmissionDecision.KEEP,
+        "Gram concordance matrix N N^T or N^T N",
+    ),
 )
 
 REGISTRATION = OperationRegistration(TOOLS, ADMISSIONS)

src/jacobian/math/incidence_structures/_models.py

@@ -10,6 +10,13 @@
 
 MAX_POINTS = 100
 MAX_BLOCKS = 100
+MAX_T = 10
+MAX_SUBSETS = 5_000
+MAX_PAIRS = 5_000
+MAX_MATRIX_CELLS = 10_000
+MAX_GRAPH_EDGES = 5_000
+MAX_LABEL_BYTES = 1_024
+MAX_RESULT_BYTES = 1_000_000
 
 
 class IncidenceStructure(StrictModel):
@@ -55,3 +62,152 @@ class DegreeProfileResult(StrictModel):
     point_degrees: tuple[tuple[str, int], ...]
     block_degrees: tuple[tuple[str, int], ...]
     total_incidences: int
+
+
+# ---------------------------------------------------------------------------
+# 3. Containment profiles (t-subset codegree profiles)
+# ---------------------------------------------------------------------------
+
+
+class ContainmentProfileRequest(StrictModel):
+    incidence: IncidenceStructure
+    t: int = Field(ge=1, le=MAX_T)
+
+
+class ContainmentProfileResult(StrictModel):
+    t: int
+    subset_profile: tuple[tuple[tuple[str, ...], int], ...]
+    histogram: tuple[tuple[int, int], ...]
+    min_multiplicity: int
+    max_multiplicity: int
+    is_constant: bool
+    constant_lambda: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# 4. Block intersection profiles
+# ---------------------------------------------------------------------------
+
+
+class IntersectionsRequest(StrictModel):
+    incidence: IncidenceStructure
+
+
+class IntersectionsResult(StrictModel):
+    pairwise: tuple[tuple[str, str, tuple[str, ...], int], ...]
+    histogram: tuple[tuple[int, int], ...]
+
+
+# ---------------------------------------------------------------------------
+# 5. Dual incidence structure
+# ---------------------------------------------------------------------------
+
+
+class DualRequest(StrictModel):
+    incidence: IncidenceStructure
+
+
+class DualResult(StrictModel):
+    points: tuple[str, ...]
+    block_ids: tuple[str, ...]
+    blocks: tuple[tuple[str, ...], ...]
+    point_map: tuple[tuple[str, str], ...]
+    block_map: tuple[tuple[str, str], ...]
+
+
+# ---------------------------------------------------------------------------
+# 6. Complement incidence structure
+# ---------------------------------------------------------------------------
+
+
+class ComplementRequest(StrictModel):
+    incidence: IncidenceStructure
+
+
+class ComplementResult(StrictModel):
+    points: tuple[str, ...]
+    block_ids: tuple[str, ...]
+    blocks: tuple[tuple[str, ...], ...]
+    correspondence: tuple[tuple[str, tuple[str, ...], tuple[str, ...]], ...]
+
+
+# ---------------------------------------------------------------------------
+# 7. Restriction (point/block deletion and restriction)
+# ---------------------------------------------------------------------------
+
+
+class RestrictionRequest(StrictModel):
+    incidence: IncidenceStructure
+    points: tuple[str, ...] = Field(default_factory=tuple)
+    block_ids: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class RestrictionResult(StrictModel):
+    points: tuple[str, ...]
+    block_ids: tuple[str, ...]
+    blocks: tuple[tuple[str, ...], ...]
+
+
+# ---------------------------------------------------------------------------
+# 8. Derived and residual incidence structures
+# ---------------------------------------------------------------------------
+
+
+class DerivedResidualRequest(StrictModel):
+    incidence: IncidenceStructure
+    point: str
+    kind: str = Field(default="derived")
+
+    @model_validator(mode="after")
+    def require_valid_kind(self) -> Self:
+        if self.kind not in ("derived", "residual"):
+            raise ValueError("kind must be 'derived' or 'residual'")
+        if self.point not in self.incidence.points:
+            raise ValueError("anchor point must be a declared point")
+        return self
+
+
+class DerivedResidualResult(StrictModel):
+    kind: str
+    anchor_point: str
+    points: tuple[str, ...]
+    block_ids: tuple[str, ...]
+    blocks: tuple[tuple[str, ...], ...]
+    source_blocks: tuple[str, ...]
+
+
+# ---------------------------------------------------------------------------
+# 9. Levi graph (bipartite incidence graph)
+# ---------------------------------------------------------------------------
+
+
+class LeviGraphRequest(StrictModel):
+    incidence: IncidenceStructure
+
+
+class LeviGraphResult(StrictModel):
+    left_vertices: tuple[str, ...]
+    right_vertices: tuple[str, ...]
+    edges: tuple[tuple[str, str], ...]
+
+
+# ---------------------------------------------------------------------------
+# 10. Gram / concordance matrix
+# ---------------------------------------------------------------------------
+
+
+class GramRequest(StrictModel):
+    incidence: IncidenceStructure
+    axis: str = Field(default="point")
+
+    @model_validator(mode="after")
+    def require_valid_axis(self) -> Self:
+        if self.axis not in ("point", "block"):
+            raise ValueError("axis must be 'point' or 'block'")
+        return self
+
+
+class GramResult(StrictModel):
+    axis: str
+    labels: tuple[str, ...]
+    matrix: tuple[tuple[int, ...], ...]