ci: shard ordinary Python checks by semantic lane (#1304)

* fix(topology): preserve non-maximal facet diagnostics

* test(external-sat): remove stale producer conclusions

* ci: shard ordinary Python checks by semantic lane

Author: morluto

.github/workflows/ci.yml

@@ -49,17 +49,33 @@ jobs:
           path: dist/
 
   python:
-    name: python
+    name: python (${{ matrix.lane }})
     runs-on: ubuntu-latest
-    timeout-minutes: 40
+    timeout-minutes: ${{ matrix.timeout-minutes }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - lane: unit
+            timeout-minutes: 10
+          - lane: component
+            timeout-minutes: 15
+          - lane: domain
+            timeout-minutes: 15
+          - lane: composition
+            timeout-minutes: 25
+          - lane: e2e
+            timeout-minutes: 15
+          - lane: provider
+            timeout-minutes: 25
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - uses: ./.github/actions/setup-python-tests
         with:
           python-version: "3.12"
-      - run: make test-ordinary
+      - run: make test-${{ matrix.lane }}
         env:
           PYTEST_ARGS: >-
             --junitxml=pytest.xml
@@ -69,17 +85,17 @@ jobs:
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: ${{ !cancelled() }}
         with:
-          name: junit-python-3.12
+          name: junit-python-${{ matrix.lane }}-3.12
           path: pytest.xml
           if-no-files-found: ignore
           retention-days: 7
       - if: ${{ !cancelled() }}
-        run: mv .coverage .coverage.python
+        run: mv .coverage .coverage.python-${{ matrix.lane }}
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: ${{ !cancelled() }}
         with:
-          name: coverage-data-python
-          path: .coverage.python
+          name: coverage-data-python-${{ matrix.lane }}
+          path: .coverage.python-${{ matrix.lane }}
           include-hidden-files: true
 
   boundaries:

CONTRIBUTING.md

@@ -25,7 +25,8 @@ make check
 
 Then open a pull request. `make setup` installs the locked development
 environment with the complete maintained Python backend stack. `make check`
-runs Ruff, mypy, and the same Lean-free ordinary pytest invocation CI uses.
+runs Ruff, mypy, and the same Lean-free ordinary test suite CI covers in fixed
+semantic groups.
 Open the PR once it is green, and add any explicitly relevant specialist
 validation called out below.
 

Makefile

@@ -9,8 +9,9 @@ ORDERING_DEFAULT_SEED := --randomly-seed=17
 PYTEST_DIAGNOSTIC_ARGS ?= --durations=10
 RUFF_PATHS := src tests benchmarks
 PYTEST_RUNNER := $(UV_RUN) python tools/pytest_lifecycle.py
-# Ordinary pytest used by `make check` and the CI python job.
-ORDINARY_PYTEST_FLAGS := -n 4 --dist worksteal --timeout=180
+# Fixed semantic lanes covering the Lean-free ordinary testpaths. CI runs these
+# independently; `make check` runs the same lanes locally in this order.
+ORDINARY_TEST_LANES := unit component domain composition e2e provider
 PUBLIC_COMMANDS := setup quick check check-external fix
 
 include make/development.mk
@@ -81,9 +82,10 @@ test-e2e: ## Complete caller-visible journeys (serial, 180s).
 		$(if $(TESTS),$(TESTS),tests/e2e) \
 		$(PYTEST_DIAGNOSTIC_ARGS) $(PYTEST_ARGS)
 
-test-ordinary: ## Lean-free ordinary pytest (same flags as CI python).
-	$(UV_RUN) pytest $(ORDINARY_PYTEST_FLAGS) \
-		$(PYTEST_DIAGNOSTIC_ARGS) $(PYTEST_ARGS)
+test-ordinary: ## Lean-free ordinary suite in the fixed CI group order.
+	@for lane in $(ORDINARY_TEST_LANES); do \
+		$(MAKE) test-$$lane || exit $$?; \
+	done
 
 test-compatibility: ## Supported-version import/API compatibility smoke.
 	$(UV_RUN) pytest -n 0 --timeout=30 --timeout-method=thread \

docs/reference/testing-strategy.md

@@ -31,6 +31,11 @@ Make targets that own storage, process, MCP, and Lean isolation. `make
 check-external` covers Lean and maintained-provider probes when those trees
 change.
 
+Hosted CI runs that same ordinary suite as six fixed semantic lanes: `unit`,
+`component`, `domain`, `composition`, `e2e`, and `provider`. These are static
+Make targets, not path-selected or timing-planned shards; `make check` runs all
+six in the same order.
+
 ## Test ownership
 
 The filesystem is the metadata. A test under `tests/domain/` is a domain test;

pyproject.toml

@@ -23,6 +23,7 @@ dependencies = [
     "mcp-types==2.0.0",
     "networkx==3.6.1",
     "pydantic>=2.12,<3",
+    "pydantic-core>=2.41,<3",
     "python-flint==0.9.0",
     "rfc8785==0.1.4",
     "sympy==1.14.0",

src/jacobian/contracts/topology.py

@@ -15,6 +15,7 @@
     field_validator,
     model_validator,
 )
+from pydantic_core import PydanticCustomError
 
 from jacobian.canonical import canonicalize_json
 from jacobian.contracts.certified_snf import (
@@ -109,7 +110,10 @@ def _require_request_complex(
         )
     for left, right in combinations(canonical, 2):
         if set(left) < set(right) or set(right) < set(left):
-            raise ValueError("facet input must contain only maximal simplices")
+            raise PydanticCustomError(
+                "topology_non_maximal_facets",
+                "facet input must contain only maximal simplices",
+            )
     closure = face_closure(tuple(canonical))
     if sum(map(len, closure)) > MAX_TOPOLOGY_FACES:
         raise ValueError(

tests/boundary/providers/external_sat/startup/test_carcara.py

@@ -84,7 +84,7 @@ def test_zero_hole_qf_uf_proof_is_independently_verified(
     produced = _produce(carcara_services, "QF_UF", "qf_uf_equality_unsat.smt2")
 
     assert produced.output["contains_holes"] is False
-    assert produced.output["conclusion"] == "UNKNOWN"
+    assert "conclusion" not in produced.output
     verified = _verify(carcara_services, produced.output["proof_uri"])
 
     assert verified.execution.status is ExecutionStatus.COMPLETED

tests/boundary/providers/external_sat/test_cadical_external_backend.py

@@ -49,7 +49,7 @@ def test_pinned_cadical_produces_a_model_and_text_drat_proof(
         )
         assert model.execution.status is ExecutionStatus.COMPLETED
         assert model.output["status"] == "ASSIGNMENT_PRODUCED"
-        assert model.output["conclusion"] == "UNKNOWN"
+        assert "conclusion" not in model.output
 
         unsatisfiable = runtime.core.sat.put_cnf(
             variable_names=("x",),
@@ -66,4 +66,4 @@ def test_pinned_cadical_produces_a_model_and_text_drat_proof(
         )
         assert proof.execution.status is ExecutionStatus.COMPLETED
         assert proof.output["status"] == "PROOF_PRODUCED"
-        assert proof.output["conclusion"] == "UNKNOWN"
+        assert "conclusion" not in proof.output

tests/boundary/providers/external_sat/test_sat_public_reproductions.py

@@ -82,7 +82,7 @@ def test_sat_public_reproductions_reach_checker_bound_results(
                 )
             )
             assert found.execution.status is ExecutionStatus.COMPLETED
-            assert found.output["conclusion"] == "UNKNOWN"
+            assert "conclusion" not in found.output
             evidence_uri = found.output[evidence_field]
             assert evidence_uri is not None
             if case["expected_status"] == "SATISFIABLE":

tests/domain/topology/test_topology_capabilities.py

@@ -481,5 +481,5 @@ def test_enriched_diagnostic_still_fails_closed_for_non_digest_error(
 
     assert result.execution.status is ExecutionStatus.ERROR
     assert result.diagnostics[0].code == "INVALID_FINITE_SIMPLICIAL_TOPOLOGY_REQUEST"
-    assert "maximal" in (result.diagnostics[0].hint or "")
+    assert "topology_non_maximal_facets" in (result.diagnostics[0].hint or "")
     assert result.artifact_uris == ()