fix+ci(pyvolca): resolve pre-existing pyright errors and gate pyright in CI

.github/workflows/pyvolca.yml

@@ -49,6 +49,12 @@ jobs:
       - name: Install pyvolca with dev extras
         run: pip install -e .[dev]
 
+      - name: Type-check with pyright
+        # Pinned pyright (see dev extras) over src/volca; config in
+        # pyproject.toml [tool.pyright]. Catches type regressions the
+        # editor LSP would show but pytest never would.
+        run: pyright
+
       - name: Download engine binary from main's latest build
         # Pull the linux-amd64 engine artefact from the most recent
         # successful build.yml run on main. test_drift.py's live_spec

AGENTS.md

@@ -89,6 +89,7 @@ A Python client lives in `pyvolca/` (own `pyproject.toml`); the MUMPS binding in
 - Simplicity: perfection = nothing left to remove. Avoid over-engineering and cognitive load.
 - **Pre-1.0 (`v0.y.z`): no backward-compatibility obligation yet** — keep wire formats and APIs clean rather than carrying cruft. Reassess at `v1.0.0`.
 - Use language servers for fast diagnostics: HLS for Haskell, pyright for the `pyvolca/` Python client.
+- Fix a diagnostic the moment you see it, even a pre-existing one you only surfaced in passing — don't defer it to "later" or leave it because it predates your change. A separate small commit keeps it out of your feature's scope.
 
 ### Open-source boundary
 - This engine stands alone — keep deployment/SaaS concerns and any customer- or product-specific names out of code, comments, and PRs.

pyvolca/pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest"]
+dev = ["pytest", "pyright==1.1.411"]
 
 [project.urls]
 Documentation = "https://volca.run/docs/guides/pyvolca/"
@@ -29,3 +29,8 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.pyright]
+include = ["src/volca"]
+typeCheckingMode = "basic"
+pythonVersion = "3.10"

pyvolca/src/volca/client.py

@@ -422,7 +422,7 @@ def _call(
         self,
         operation_id: str,
         *,
-        substitutions: list[dict] | None = None,
+        substitutions: list[SubstitutionLike] | None = None,
         **kwargs: Any,
     ) -> Any:
         """Dispatch an OpenAPI operation by ``operationId``.

pyvolca/src/volca/types.py

@@ -654,8 +654,12 @@ def from_json(
         if fetch is None:
             inner_fetch = None
         else:
-            def inner_fetch(o: int, l: int | None) -> dict:
-                return fetch(o, l)["results"]
+            page_fetch = fetch  # narrowed to non-None for the closure below
+
+            def _fetch_results(o: int, l: int | None) -> dict:
+                return page_fetch(o, l)["results"]
+
+            inner_fetch = _fetch_results
         return cls(
             consumers=SearchResults.from_raw(
                 d["results"], parse=ConsumerResult.from_json, fetch=inner_fetch,