feat: add an explicit shutdown API for lanes and the auto-transition timer

[bagowix]

Summary

A coordinated breaker owns background work that had no deterministic end. The lane — a daemon thread for a sync Storage, an asyncio task for an AsyncStorage — exited only once the coordinator was garbage collected and the next tick observed a dead weakref. The auto_transition timer was cancelled when the breaker left OPEN, never on teardown. So a service dropping a breaker could not flush queued shared writes, could not know when its threads were gone, and an async lane outliving asyncio.run() produced "task was destroyed but it is pending".

This adds CircuitBreaker.close() / aclose() and Registry.close_all() / aclose_all(), over SyncCoordinator.shutdown() / AsyncCoordinator.shutdown().

Shutdown drains queued writes in FIFO order, wakes a parked lane through a sentinel op rather than waiting out poll_interval, joins the thread or awaits the task, and cancels the timer without arming another. It is idempotent and safe to call from any thread. The weakref path stays as the safety net for abandoned breakers.

Decisions the issue left open

• Flush policy: drain. Ops already queued run before the lane exits, so a trip recorded just before shutdown still reaches the backend. Writes the degraded gate would drop are still dropped.
• Shutdown is terminal — the lane does not restart. Afterwards the breaker keeps protecting calls on local state and drops shared writes, exactly as while the storage is degraded. Registry.close_all() keeps the cache, so get() returns the same torn-down instance instead of silently starting a fresh lane.
• close() / aclose() follow the runtime-matching contract already enforced on call(): calling the wrong one on a coordinated breaker raises InterlockError rather than silently leaving the lane running.
• No context-manager support. with breaker: is already the protected block; contextlib.closing(breaker) covers the need.

One thing found while implementing

Dropping the lane without dropping the cached shared view leaves the breaker wedged: nothing refreshes the cache any more, so a peer's OPEN would never expire and every call would be rejected forever. close() therefore clears the view after the join (so no in-flight write can re-adopt it) and falls back to local state, reported through on_state_change like any other transition. Covered by test__close__on_an_adopted_shared_open__falls_back_to_local_state.

Also fixes #97

Both lanes pulled an op off the queue before resolving the weak reference, so a lane stopping on a collected coordinator never called task_done(): unfinished_tasks stayed positive forever and wait_idle() could never return. Both drop paths now release the dequeued op. The issue rates this Low because nothing outside a test could reach the hang — the shutdown API is exactly what makes it reachable, which is why the two ship together.

Tests

New tests/test_shutdown.py (24 tests) runs real lane threads and tasks with poll_interval = 3600.0, so shutdown has to wake the lane through the sentinel rather than wait it out. Covers: lane stopped and joined (sync + async), drain with writes in flight, shutdown while degraded, double shutdown, shutdown before the lane started, terminal semantics, timer cancelled and never re-armed, runtime mismatch, registry close-all, fallback to local state, and the task_done() drop-path invariant with join() guarded by a timeout.

542 passed, 2 skipped, coverage 100.00%.

Checklist

• Tests added or updated (suite stays at 100% coverage)
• uv run ruff format --check and uv run ruff check pass
• uv run mypy and uv run pyright pass
• Docs updated (docs/) for user-facing changes
• CHANGELOG.md [Unreleased] updated
• Commits follow Conventional Commits

Related issues

Closes #98
Closes #97

[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
breaker.py
registry.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 feat/explicit-shutdown (20cc334) with main (f0ca0ef)}