add-or-fix-type-checking

Narrow the union with an explicit check such as `if x is None: raise ValueError(...)` before accessing attributes. All three checkers (mypy, ty, pyrefly) track this narrowing, including negative isinstance forms. Never use assert for narrowing since it is stripped by python -O.

Run mypy from the src directory with `mypy --config-file pyproject.toml <file>`, run ty from the repo root with `make ty`, and run pyrefly through `make quality`. Activate the conda environment first so all checkers resolve the correct interpreter.

Prefer @overload when a method's return type depends on input types, since it gives checkers precise signatures and eliminates casts at call sites. Use cast() only after structural validation when the checker cannot infer the type, and before resorting to type: ignore.

Third-party packages may ship incomplete stubs missing kwargs or attributes. Regenerate stubs into the typings directory with `make stubs`, which all three checkers reference via mypy_path, extra-paths, and search-path configuration.

Use it only for genuine third-party stub defects that cannot be solved by narrowing, overloads, generics, or cast. Always include the specific error code such as `# type: ignore[call-arg]` and document the reason; bare ignores are prohibited.