refactor: enforce all-mode Python typing and full Ruff preview

.github/workflows/ci.yml

@@ -18,22 +18,33 @@ defaults:
 
 jobs:
   test:
+    name: test (${{ matrix.python-version }})
+    env:
+      UV_PYTHON: ${{ matrix.python-patch }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
     permissions:
       contents: read
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - python-version: "3.11"
+            python-patch: "3.11.16"
+          - python-version: "3.12"
+            python-patch: "3.12.14"
+          - python-version: "3.13"
+            python-patch: "3.13.15"
+          - python-version: "3.14"
+            python-patch: "3.14.7"
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - run: bash .github/scripts/actionlint.sh
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ matrix.python-patch }}
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.12.17"
@@ -93,7 +104,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: "3.12"
+          python-version: "3.12.14"
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.12.17"

.github/workflows/mutation-audit.yml

@@ -20,7 +20,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: "3.12"
+          python-version: "3.12.14"
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.12.17"

.python-version

@@ -0,0 +1 @@
+3.12.14

AGENTS.md

@@ -3,10 +3,10 @@
 - Research upstream tools before adding enforcement. Keep rules in native tool
   configuration and orchestration in standard tasks. Add custom checks only
   for requirements established tools cannot express; document that gap.
-- Fix failures rather than weakening rules or excluding code. Narrow exceptions
-  for verified tool limitations require human approval and an exact record in
-  `maintainers/quality-exceptions.json`. Never approve quality-policy changes
-  on a human reviewer's behalf.
+- Fix failures rather than weakening policy. Judge pragmatic exceptions against
+  compatibility constraints and verified tool limits; do not use them to postpone
+  cleanup. Never impersonate a human reviewer or submit review approval on their
+  behalf.
 - Keep reviewer and repository-administration credentials outside ordinary
   automation.
 - Preserve shared behavioral scenarios and coordinate contract changes with

tests/conftest.py → conftest.py

@@ -6,15 +6,15 @@
 
 import pytest
 
-pytest_plugins = ["pytester"]
+pytest_plugins = ["pytester", "volcano_sdk._tests.realtime_probes"]
 
 _WARNING_PREFIX = "ignore:'asyncio.iscoroutinefunction' is deprecated"
 _REVIEWED_WARNING = f"{_WARNING_PREFIX}:{DeprecationWarning.__name__}"
 
 
 def _reviewed_warning_filter(item: pytest.Item, marker: pytest.Mark) -> bool:
     return (
-        item.nodeid.startswith("tests/unit/test_durable_authoring.py::")
+        item.nodeid.startswith("src/volcano_sdk/_tests/test_durable_authoring.py::")
         and marker.args == (_REVIEWED_WARNING,)
         and not marker.kwargs
     )
@@ -87,7 +87,11 @@ def pytest_terminal_summary(self, terminalreporter: _TerminalSummary) -> None:
 def _selection_errors(config: pytest.Config) -> set[str]:
     errors: set[str] = set()
     roots = config.getoption("file_or_dir")
-    if roots and roots != ["tests/unit"] and not _mutation_checkout(config):
+    if (
+        roots
+        and roots != ["tests/unit", "src/volcano_sdk/_tests"]
+        and not _mutation_checkout(config)
+    ):
         errors.add("focused test paths")
     if config.getoption("ignore") or config.getoption("ignore_glob"):
         errors.add("ignored test paths")

maintainers/auth-internal-boundaries.md

@@ -0,0 +1,45 @@
+# Typed authentication boundaries
+
+Keep the existing public Auth methods while giving sibling facades an explicit,
+typed request interface. `AuthRequests` owns refresh, replay, revocation, and
+session ownership. One instance is shared by the client and authentication facade;
+its state is never copied during a request. Email and OAuth mixins group public
+operations by responsibility. Response validation and client capabilities live in
+private modules with normal internal names.
+
+The public 31-method Auth parameter lists are unchanged. `Auth(client)` remains
+valid; a keyword-only `_requests` argument lets the client inject its shared
+coordinator. No internal lifecycle method is added to the public facade. Existing
+concurrency, credential-scoping, package typing, and full-coverage tests check this
+boundary.
+
+Research checked on 2026-09-24:
+
+- **Adopt:** [Stripe](https://github.com/stripe/stripe-python/blob/master/stripe/_stripe_client.py)
+  creates one request coordinator and injects it into resource services.
+- **Adapt:** [HTTPX](https://github.com/encode/httpx/blob/master/httpx/_client.py)
+  uses a common typed client base and optional transport injection. Our shared
+  base only provides authentication capabilities to the operation groups.
+- **Reject:** [Supabase Auth](https://github.com/supabase/auth-py/blob/main/supabase_auth/_sync/gotrue_client.py)
+  demonstrates dependency injection but also dynamically binds some service
+  methods. Static classes and explicit signatures keep our all-mode type checks
+  effective.
+
+The optional internal injection preserves standalone construction while avoiding
+callback rebinding or public forwarding methods for private operations.
+
+The same static grouping keeps `GeneratedTransport` operations in six modules:
+authentication, account management, database, storage, execution, and locks. They
+share one typed HTTP configuration base; response normalization is independent of
+the operation groups. All 57 operation parameter lists remain unchanged.
+
+Public facade constructors also accept a `VolcanoClient` directly. Two typed
+adapters obtain its private authentication or facade context; this preserves the
+existing constructors without publishing internal client methods. Dataclass
+builders retain their parameter names and defaults and resolve the context before
+an operation. Each adapter's exact private factory call has documented Ruff and
+Basedpyright exceptions, checked against its literal call and function scope.
+
+The context protocols describe private client wiring. They are not root-package
+exports or documented consumer extension points; direct construction tests use
+`VolcanoClient` and the documented public facade methods.

maintainers/contract-typing.md

@@ -17,6 +17,6 @@ Sources: [typeshed signatures](https://github.com/python/typeshed/blob/main/stub
 [Behave registration](https://github.com/behave/behave/blob/v1.3.3/behave/step_registry.py),
 [Pyright partial stub resolution](https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/partialStubService.ts).
 
-`tests/typing/contract_steps.py` checks retained argument types and deliberately
+`src/volcano_sdk/_tests/typing/contract_steps.py` checks retained argument types and deliberately
 invalid calls. The shared scenarios still require an executed contract run
 against disposable infrastructure; `poe contract-check` only checks discovery.

maintainers/coverage.md

@@ -1,17 +1,18 @@
 # Runtime coverage
 
-`uv run --locked poe coverage` measures every Python file under `src/volcano_sdk`,
+`uv run --locked poe coverage` measures every handwritten runtime module under `src/volcano_sdk`,
 including unimported files and namespace directories. Native coverage.py
 configuration requires 100% line and branch coverage. `poe quality` includes
 this task, and CI preserves `reports/coverage.json` for each quality run.
 
-The generated OpenAPI client and declaration-only code are excluded. Coverage
+The generated OpenAPI client, private `_tests` package, and declaration-only
+code are excluded. Coverage
 pragmas cannot suppress missing lines or branches. Tests exercise this policy
 with unimported modules, missing branches, and ineffective pragma comments.
 Examples, generator tooling, package contents, and installed consumers have
 separate smoke and gate tests; they are outside runtime coverage.
 
-Coverage runs in an isolated Python 3.12 environment with the same lockfile.
+Coverage runs in an isolated Python 3.12.14 environment with the same lockfile.
 The ordinary test task and all other quality checks still run on the selected
 Python version, including every supported version from 3.11 through 3.14 in CI.
 uv's isolation keeps coverage from replacing that interpreter or its environment.

maintainers/mutation-testing.md

@@ -4,19 +4,25 @@
 handwritten runtime module. CI runs the same `checks` and `mutation` tasks,
 assigning one handwritten module to each independent matrix job. Git's current
 handwritten module inventory determines the jobs, including newly added modules.
-`Mutation Gate` requires every module job, and `Quality Gate` requires it and the Python test matrix. The
-weekly audit runs the same full mutation task without a debt baseline.
+`Mutation Gate` requires every module job. `Quality Gate` requires it and the
+Python test matrix. The weekly audit runs the same full mutation task without a
+debt baseline.
 
 Mutmut's [native configuration](https://mutmut.readthedocs.io/en/latest/) lives
-in `pyproject.toml`; it excludes only the generated OpenAPI client. Mutmut can
-select modules by name but returns success when mutants survive.
+in `pyproject.toml`; it excludes the generated OpenAPI client and private test
+package. Mutmut can select modules by name but returns success when mutants
+survive.
 `scripts/mutation.sh` selects the full handwritten inventory from Git and
 `scripts/mutation_results.py` reads each selected module's native metadata. The
 report at `reports/mutation.json` distinguishes killed, statically invalid,
 surviving, uncovered, timed-out, crashed, interrupted, and missing results.
-Mutmut creates mutants inside functions. Export-only modules remain in the
-inventory; the runner verifies that they define no functions and records them
-as unmutatable. Coverage and installed-package checks still include them.
+Mutmut creates mutants inside functions, but some functions have no candidates:
+zero-argument getter delegation and protocol declarations are examples. Every
+module remains in the inventory. The runner calls the pinned Mutmut generator's
+`mutate_file_contents` API to verify zero candidates, then records the module as
+unmutatable. This uses the same operators as the native run, without source
+heuristics or per-module exemptions. Coverage and installed-package checks still
+include these modules.
 A pytest internal error is a harness crash, not a killed mutant.
 The pinned Pyrefly check covers the handwritten runtime and rejects
 type-invalid mutants before pytest;

maintainers/property-tests.md

@@ -5,7 +5,7 @@ seed for the run is saved in `reports/hypothesis/seed.txt`. Replay the same
 inputs with the pinned Hypothesis version:
 
 ```sh
-VOLCANO_PROPERTY_SEED=12345 uv run pytest tests/unit/test_encoding_properties.py
+VOLCANO_PROPERTY_SEED=12345 uv run --locked poe test
 ```
 
 The quality command writes `reports/unit.xml`, including Hypothesis's minimized