Problem
The notification and operational alerting callbacks throughout the codebase are untyped. Functions like notify_callback (used to deliver per-user watchlist matches and channel-wide announcements) and ops_alert_fn (used to surface operational errors to operators) are passed as bare Callable parameters without specifying their argument types, return types, or error-handling contracts. This means a caller can pass a function with the wrong signature and the error surfaces only at runtime -- the type checker and linters cannot catch the mismatch. The W24 eval's finding that 18 modules suppress mypy (in the sibling local-ci project) highlights the broader cost of skipping typed callback contracts in codebases that aspire to type coverage.
Acceptance Criteria
Implementation Notes
Primary files to modify:
src/paperscout/bot.py -- notify_channel(), notify_user(), and any callback parameters
src/paperscout/monitor.py -- poll loop callback wiring, ops_alert_fn parameter
src/paperscout/models.py or new src/paperscout/protocols.py -- protocol definitions
pyproject.toml -- consider removing any ignore_errors overrides on modified modules
References
- Eval finding: W24 horizon item (untyped callbacks cluster)
- Related files:
src/paperscout/bot.py, src/paperscout/monitor.py, src/paperscout/config.py, src/paperscout/models.py
Problem
The notification and operational alerting callbacks throughout the codebase are untyped. Functions like
notify_callback(used to deliver per-user watchlist matches and channel-wide announcements) andops_alert_fn(used to surface operational errors to operators) are passed as bareCallableparameters without specifying their argument types, return types, or error-handling contracts. This means a caller can pass a function with the wrong signature and the error surfaces only at runtime -- the type checker and linters cannot catch the mismatch. The W24 eval's finding that 18 modules suppress mypy (in the sibling local-ci project) highlights the broader cost of skipping typed callback contracts in codebases that aspire to type coverage.Acceptance Criteria
NotifyCallbackandOpsAlertFnastyping.Protocolclasses with explicit__call__signatures (argument names, types, return type)bot.py,monitor.py, and any other modules are annotated with the new Protocol types--strictor equivalent strictness for callback signaturesImplementation Notes
Primary files to modify:
src/paperscout/bot.py--notify_channel(),notify_user(), and any callback parameterssrc/paperscout/monitor.py-- poll loop callback wiring,ops_alert_fnparametersrc/paperscout/models.pyor newsrc/paperscout/protocols.py-- protocol definitionspyproject.toml-- consider removing anyignore_errorsoverrides on modified modulesReferences
src/paperscout/bot.py,src/paperscout/monitor.py,src/paperscout/config.py,src/paperscout/models.py