fix: isolate EventListener failures from protected calls and lanes

[bagowix]

Summary

An EventListener that raises could damage the breaker it observes. Hooks were invoked directly at every call site, so a bug in optional observability became a new failure source in a fault-tolerance library.

Three distinct consequences of one root cause, all confirmed in the code:

1. The protected call. on_call raising in Engine._settle replaced a successful result with an observability exception, or masked the dependency's own error.

2. Silent death of the coordinator lane. poll_once calls _accept outside its try (interlock/_coordination.py:248, 417), and _accept → Engine._on_shared_view → _emit_transitions → on_state_change. A raising listener propagated out of _sync_lane_tick / _async_lane_tick and terminated the daemon thread / asyncio task permanently. From then on the breaker never refreshed the shared view and never flushed queued writes again — with nothing surfaced anywhere.

3. False diagnosis. Inside execute_op the same exception was caught by the generic except Exception and routed to _degrade, so a listener bug was reported to the application as a storage failure via on_storage_degraded.

The fix. A new interlock/_notify.py holds notify() — now the only place an EventListener hook is ever invoked:

• dispatch by name via getattr, so every hook is optional and pre-1.2 / pre-2.0 listeners keep working;
• an Exception is logged to the interlock logger at ERROR with the traceback and hook/breaker context, then ignored;
• BaseException (KeyboardInterrupt, asyncio.CancelledError) is not caught — cancellation propagates as everywhere else in interlock.

Applied to core, storage and pipeline hooks (_engine.py, pipeline.py, integrations/tenacity.py). User-supplied policy callbacks deliberately keep their previous semantics and still raise — a FailureClassifier, a pipeline fallback function, a tenacity before_sleep hook — because they shape the call's behaviour rather than observe it.

Incidentally removes _NoopListener, _NOOP_LISTENER and two ad-hoc _notify* helpers: the engine now holds EventListener | None, and the no-listener path skips dispatch entirely instead of calling a no-op method.

No public API change. The EventListener protocol is unchanged; the guarantees around it got stronger. One behavioural nuance worth review: a hook missing from a listener is now skipped instead of raising AttributeError, which makes the whole protocol uniformly optional — consistent with how the storage and pipeline hooks already behaved, and static checkers still catch a missing core hook at the call site.

Checklist

• Tests added or updated (suite stays at 100% coverage) — new tests/test_notify.py (19 tests) + ExplodingListener fixture in conftest.py, 3 tests in test_pipeline.py, 2 in test_tenacity.py. Written test-first: 5 failed with RuntimeError: listener ... exploded before the fix. Total 517 passed / 2 skipped, coverage 100.00%.
• uv run ruff format --check and uv run ruff check pass.
• uv run mypy and uv run pyright pass (both strict).
• Docs updated (docs/) — new "Listener failures are isolated" section in docs/guides/observability.md, updated pipeline.md, refreshed EventListener docstrings, llms-full.txt regenerated.
• CHANGELOG.md [Unreleased] updated.
• Commits follow Conventional Commits.

Standalone invariant holds: the entire v1 suite passes unmodified — in existing test files only import lines changed, not a single assertion. Benchmarks (benchmarks/, 21 tests) still pass; the no-listener hot path got marginally cheaper.

Related issues

Closes #83.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
interlock
_coordination.py
_engine.py
_notify.py
pipeline.py
protocols.py
interlock/integrations
tenacity.py
Project Total

This report was generated by python-coverage-comment-action

[codspeed-hq]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing fix/isolate-listener-failures (2ae8cb0) with main (7e6d9d2)}