Cursor rule

1---
2description: Background task lifecycle, shutdown ordering, and loop invariants
3globs: app/worker/**/*.py,app/main.py
4alwaysApply: false
5---
6 
7# Background Task Lifecycle
8 
9Background tasks (`WorkerPool`, `EsIndexer`, `RollupScheduler`) follow a
10`start()` / `stop()` shape with an `asyncio.Event` stop signal and a single
11`asyncio.create_task(..., name=...)`. The skeleton matters less than the
12decisions below — get these wrong and you lose data or hang a deploy.
13 
14## Drain vs. cancel on `stop()` (a correctness decision)
15 
16- If the task holds **un-acked, un-persisted work**, drain it before cancelling.
17  `WorkerPool.stop()` does `await queue.join()` with a timeout, *then* cancels.
18- If the task's work is **idempotent / replayable** (the outbox re-indexes, the
19  next tick re-aggregates), set the stop event and cancel directly —
20  `EsIndexer` / `RollupScheduler`.
21 
22When adding a task, ask: would cancelling mid-flight lose anything? That answer
23picks the variant.
24 
25## Loop invariants
26 
27- Idle interruptibly — never block shutdown for a full interval:
28 
29```python
30# ✅ wakes immediately on stop
31try:
32    await asyncio.wait_for(self._stop_event.wait(), timeout=self._interval)
33except asyncio.TimeoutError:
34    pass  # interval elapsed
35# ❌ asyncio.sleep(self._interval)  # ignores the stop signal
36```
37 
38- The loop body **catches and logs**, never lets an exception kill the task.
39- Consumers must call `task_done()` for every `get()`, even on error.
40 
41## Shutdown ordering in `app/main.py` lifespan
42 
43`ingestion.stop_accepting()` → `worker.stop()` (drain) → `es_indexer.stop()` →
44`rollup.stop()` → **then** close Mongo/ES/Redis clients. Never close a client a
45running task still uses.
46