Summary

Signal._handlers was typed list[Callable[..., None]] and fire(**kwargs: Any) forwarded arbitrary kwargs, so a typo at a fire site or a missing parameter at a handler only surfaced when a real service event happened to dispatch. mypy could not help catch dispatch mismatches when the contract shifted.

Locks the contract down with a ServiceStateChangeHandler Protocol and an explicit keyword-only fire(*, zeroconf, service_type, name, state_change). register_handler / unregister_handler keep accepting Callable[..., None] for back-compat and cast at the boundary, matching the suggestion in the issue.

Closes #1779

Changes

• Add ServiceStateChangeHandler Protocol in zeroconf._services describing the (zeroconf, service_type, name, state_change) keyword signature; re-export from the top-level zeroconf package.
• Tighten Signal._handlers to list[ServiceStateChangeHandler] and Signal.fire to a keyword-only signature with the four named parameters.
• Keep SignalRegistrationInterface.register_handler / unregister_handler accepting Callable[..., None] and cast() to the Protocol on the way in.
• Add tests covering dispatch, the typo-kwarg failure mode, positional-arg rejection, and the public export.

Test plan

• SKIP_CYTHON=1 poetry run pytest tests/ (full suite green: 396 passed, 2 skipped, 5 xfailed, 3 xpassed).
• poetry run ruff check src/zeroconf/_services/__init__.py src/zeroconf/__init__.py tests/test_services.py (clean).
• poetry run ruff format --check on the same files (clean).
• REQUIRE_CYTHON=1 Cython regeneration succeeds for _services/__init__.py (and every other module in TO_CYTHONIZE), so the build path still works against the new Protocol class.

Generated by Kōan

Quality Report

Changes: 3 files changed, 108 insertions(+), 8 deletions(-)

Code scan: clean

Tests: passed (4 PASSED)

Branch hygiene: clean

Generated by Kōan post-mission quality pipeline