taskflow-meter 1.0.0__tar.gz → 1.2.0__tar.gz

taskflow_meter-1.0.0/README.md → taskflow_meter-1.2.0/PKG-INFO

@@ -1,12 +1,59 @@
+Metadata-Version: 2.5
+Name: taskflow-meter
+Version: 1.2.0
+Summary: Monitoring interfaces (ASGI, WSGI, datasource) for OpenStack TaskFlow flow execution progress
+Project-URL: Homepage, https://github.com/daipham3213/taskflow.meter
+Project-URL: Source, https://github.com/daipham3213/taskflow.meter
+Project-URL: Issues, https://github.com/daipham3213/taskflow.meter/issues
+Project-URL: Changelog, https://github.com/daipham3213/taskflow.meter/releases
+Author-email: Pham Le Gia Dai <daipham.3213@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: asgi,monitoring,openstack,taskflow,workflow,wsgi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: oslo-config>=6.9.0
+Requires-Dist: taskflow>=4.2.0
+Provides-Extra: all
+Requires-Dist: alembic>=1.2.0; extra == 'all'
+Requires-Dist: kombu>=5.1.0; extra == 'all'
+Requires-Dist: oslo-messaging>=6.0.0; extra == 'all'
+Requires-Dist: sqlalchemy>=1.4.0; extra == 'all'
+Provides-Extra: amqp
+Requires-Dist: kombu>=5.1.0; extra == 'amqp'
+Provides-Extra: oslo-messaging
+Requires-Dist: oslo-messaging>=6.0.0; extra == 'oslo-messaging'
+Provides-Extra: sqlalchemy
+Requires-Dist: alembic>=1.2.0; extra == 'sqlalchemy'
+Requires-Dist: sqlalchemy>=1.4.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
 # taskflow-meter
 
+[![ci](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml)
+[![conformance](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 Monitoring interfaces — ASGI, WSGI, datasources, transports — for observing
 [OpenStack TaskFlow](https://opendev.org/openstack/taskflow) flow execution
 progress.
 
-> **Status: pre-alpha.** The packaging, tooling and CI skeleton are in place
-> (milestone M0). The design is specified in [`docs/PLAN.md`](docs/PLAN.md);
-> functionality lands milestone by milestone against it.
+```bash
+pip install taskflow-meter
+```
 
 ## What it is for
 
@@ -73,9 +120,13 @@ polling anything.
 
 ```bash
 taskflow-meter upgrade --store-url postgresql://host/meter
-taskflow-meter collect --amqp-url amqp://broker// --store-url postgresql://host/meter
+taskflow-meter collect --url amqp://broker// --store-url postgresql://host/meter
 taskflow-meter serve   --store-url postgresql://host/meter
 ```
+
+Inside OpenStack, `--transport oslo-messaging` puts the events on the
+notification bus the service is already configured for, instead of opening a
+broker connection of its own.
 One caveat for WSGI deployments: a synchronous worker holds a thread for as
 long as an SSE stream stays open, so use gevent or eventlet workers for
 streaming, or let clients poll `/events?since_seq=` instead.
@@ -156,8 +207,37 @@ serving an empty stream that cannot be told apart from silence.
 
 ## Requirements
 
-- Python 3.11+
-- taskflow 6.4.0+
+- Python 3.10+
+- taskflow 4.2.0+
+- oslo.config 6.9.0+
+
+Floors are deliberately low: this package is meant to be co-installed into
+a service whose dependency versions it does not get to choose. They are the
+oldest release of each library the suite actually passes against, not the
+oldest that looks plausible -- a `lowest-direct` CI job installs exactly
+these and runs the whole suite on them.
+
+Everything else is optional, and only needed by the feature that imports it:
+
+| Extra | Pulls in | Needed for |
+| --- | --- | --- |
+| `sqlalchemy` | SQLAlchemy 1.4+, alembic 1.2+ | The collector's own store |
+| `amqp` | kombu 5.1+ | Publishing events to a broker |
+| `oslo-messaging` | oslo.messaging 6.0+ | Publishing onto the service's own notification bus |
+| `all` | all three | |
+
+The contrib adapters declare no dependency on their hosts -- a deployment
+mounting the meter in Django already has Django. They are tested against
+Django 3.2, Flask 2.3.3, FastAPI 0.100, Pecan 1.4 and PasteDeploy 2.0.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [`docs/guide.md`](docs/guide.md) | Deploying it: configuration, every host, and how to read completion and current-task out of the API |
+| [`docs/design.md`](docs/design.md) | How it works and why -- what taskflow does and does not record, and the rules the embedding code obeys |
+| [`docs/releasing.md`](docs/releasing.md) | Cutting a release |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed |
 
 ## Examples
 
@@ -186,6 +266,15 @@ uvx tox -e py312         # tests on one interpreter
 uvx tox                  # the whole matrix
 ```
 
+CI also runs the suite with every declared dependency floor installed exactly,
+which is the only job that checks those floors are real. To reproduce it:
+
+```bash
+uv lock --python 3.10 --resolution lowest-direct
+uv sync --python 3.10 --group dev --all-extras --resolution lowest-direct
+uv run --frozen --no-sync pytest
+```
+
 Because the version is derived from git history, a shallow clone or a checkout
 with no tags will build as `0.0.0`. CI checks out with full history.
 

taskflow_meter-1.0.0/PKG-INFO → taskflow_meter-1.2.0/README.md

@@ -1,62 +1,18 @@
-Metadata-Version: 2.5
-Name: taskflow-meter
-Version: 1.0.0
-Summary: Monitoring interfaces (ASGI, WSGI, datasource) for OpenStack TaskFlow flow execution progress
-Project-URL: Homepage, https://github.com/daipham3213/taskflow-meter
-Project-URL: Source, https://github.com/daipham3213/taskflow-meter
-Project-URL: Issues, https://github.com/daipham3213/taskflow-meter/issues
-Project-URL: Changelog, https://github.com/daipham3213/taskflow-meter/releases
-Author-email: Pham Le Gia Dai <daipham.3213@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: asgi,monitoring,openstack,taskflow,workflow,wsgi
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: System Administrators
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: System :: Monitoring
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: oslo-cache>=3.0.0
-Requires-Dist: oslo-config>=9.0.0
-Requires-Dist: oslo-serialization>=2.18.0
-Requires-Dist: oslo-utils>=3.33.0
-Requires-Dist: stevedore>=1.20.0
-Requires-Dist: taskflow>=6.4.0
-Provides-Extra: all
-Requires-Dist: alembic>=1.13; extra == 'all'
-Requires-Dist: kombu>=5.0; extra == 'all'
-Requires-Dist: oslo-cache[dogpile]>=3.0.0; extra == 'all'
-Requires-Dist: oslo-cache[etcd3gw]>=3.0.0; extra == 'all'
-Requires-Dist: prometheus-client>=0.20; extra == 'all'
-Requires-Dist: sqlalchemy>=2.0; extra == 'all'
-Provides-Extra: amqp
-Requires-Dist: kombu>=5.0; extra == 'amqp'
-Provides-Extra: etcd
-Requires-Dist: oslo-cache[etcd3gw]>=3.0.0; extra == 'etcd'
-Provides-Extra: memcache
-Requires-Dist: oslo-cache[dogpile]>=3.0.0; extra == 'memcache'
-Provides-Extra: prometheus
-Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
-Provides-Extra: sqlalchemy
-Requires-Dist: alembic>=1.13; extra == 'sqlalchemy'
-Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
-Description-Content-Type: text/markdown
-
 # taskflow-meter
 
+[![ci](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml)
+[![conformance](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 Monitoring interfaces — ASGI, WSGI, datasources, transports — for observing
 [OpenStack TaskFlow](https://opendev.org/openstack/taskflow) flow execution
 progress.
 
-> **Status: pre-alpha.** The packaging, tooling and CI skeleton are in place
-> (milestone M0). The design is specified in [`docs/PLAN.md`](docs/PLAN.md);
-> functionality lands milestone by milestone against it.
+```bash
+pip install taskflow-meter
+```
 
 ## What it is for
 
@@ -123,9 +79,13 @@ polling anything.
 
 ```bash
 taskflow-meter upgrade --store-url postgresql://host/meter
-taskflow-meter collect --amqp-url amqp://broker// --store-url postgresql://host/meter
+taskflow-meter collect --url amqp://broker// --store-url postgresql://host/meter
 taskflow-meter serve   --store-url postgresql://host/meter
 ```
+
+Inside OpenStack, `--transport oslo-messaging` puts the events on the
+notification bus the service is already configured for, instead of opening a
+broker connection of its own.
 One caveat for WSGI deployments: a synchronous worker holds a thread for as
 long as an SSE stream stays open, so use gevent or eventlet workers for
 streaming, or let clients poll `/events?since_seq=` instead.
@@ -206,8 +166,37 @@ serving an empty stream that cannot be told apart from silence.
 
 ## Requirements
 
-- Python 3.11+
-- taskflow 6.4.0+
+- Python 3.10+
+- taskflow 4.2.0+
+- oslo.config 6.9.0+
+
+Floors are deliberately low: this package is meant to be co-installed into
+a service whose dependency versions it does not get to choose. They are the
+oldest release of each library the suite actually passes against, not the
+oldest that looks plausible -- a `lowest-direct` CI job installs exactly
+these and runs the whole suite on them.
+
+Everything else is optional, and only needed by the feature that imports it:
+
+| Extra | Pulls in | Needed for |
+| --- | --- | --- |
+| `sqlalchemy` | SQLAlchemy 1.4+, alembic 1.2+ | The collector's own store |
+| `amqp` | kombu 5.1+ | Publishing events to a broker |
+| `oslo-messaging` | oslo.messaging 6.0+ | Publishing onto the service's own notification bus |
+| `all` | all three | |
+
+The contrib adapters declare no dependency on their hosts -- a deployment
+mounting the meter in Django already has Django. They are tested against
+Django 3.2, Flask 2.3.3, FastAPI 0.100, Pecan 1.4 and PasteDeploy 2.0.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [`docs/guide.md`](docs/guide.md) | Deploying it: configuration, every host, and how to read completion and current-task out of the API |
+| [`docs/design.md`](docs/design.md) | How it works and why -- what taskflow does and does not record, and the rules the embedding code obeys |
+| [`docs/releasing.md`](docs/releasing.md) | Cutting a release |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed |
 
 ## Examples
 
@@ -236,6 +225,15 @@ uvx tox -e py312         # tests on one interpreter
 uvx tox                  # the whole matrix
 ```
 
+CI also runs the suite with every declared dependency floor installed exactly,
+which is the only job that checks those floors are real. To reproduce it:
+
+```bash
+uv lock --python 3.10 --resolution lowest-direct
+uv sync --python 3.10 --group dev --all-extras --resolution lowest-direct
+uv run --frozen --no-sync pytest
+```
+
 Because the version is derived from git history, a shallow clone or a checkout
 with no tags will build as `0.0.0`. CI checks out with full history.
 

taskflow_meter-1.2.0/docs/design.md

@@ -0,0 +1,171 @@
+# How taskflow-meter works, and why
+
+The [guide](guide.md) covers deploying it. This covers the reasoning
+underneath: what taskflow does and does not record, what follows from that,
+and the rules the embedding code has to obey. It is here so the next person
+to change something knows which parts are load-bearing.
+
+---
+
+## 1. What taskflow gives us
+
+Everything else follows from these. They are properties of taskflow, verified
+against it rather than assumed. The suite keeps them honest from two
+directions: `tests/functional/test_packaging.py` pins the API names the
+package relies on, and `tests/functional/test_cross_process.py` proves the
+behaviour that matters most -- progress reported by a task in one process
+being readable from another.
+
+| Fact | Consequence |
+| --- | --- |
+| `engine.notifier` fires on flow state transitions, `engine.atom_notifier` on atom state transitions | A `Listener` sees state changes, and only state changes |
+| `task.update_progress()` is handled by `TaskAction._on_update_progress`, which writes to storage and **never re-emits on `atom_notifier`** | A listener cannot see intra-task progress. Reading it live needs a separate tap on each atom's own notifier |
+| `Task.TASK_EVENTS` is exactly `('update_progress',)` | That tap has one event to bind, and no others will appear |
+| `storage.set_task_progress()` write-throughs to the persistence backend, as `meta['progress']` and `meta['progress_details']` | Fine-grained progress **is** durable, and readable from another process |
+| `LogBook` has `created_at`/`updated_at`; `FlowDetail` and `AtomDetail` have neither | No per-atom start or end times exist to report. Observation times are stamped by the meter, and mean only when it looked |
+| Flow DAG edges are not persisted -- a `FlowDetail` holds a flat set of atoms | Nothing read from persistence can draw the graph. Topology needs the in-process path |
+| `Connection` exposes `get_logbooks()`, `get_flows_for_book()`, `get_atoms_for_flow()`, with no filtering or paging | Listing is a full scan |
+| Progress callbacks are proxied back from remote workers | Worker-based engines report progress the same way |
+| taskflow discovers backends through stevedore entry points | Our own plugins follow the same convention |
+
+**The bottom line, and the reason this package can exist:** a deployment
+already using a shared persistence backend can be monitored *including
+per-task progress* with no changes to flow code. The in-process path is an
+enhancement -- lower latency, plus the graph -- not a prerequisite.
+
+The `memory` backend is the exception: per-process, and invisible from
+anywhere else.
+
+## 2. Decisions, and what they cost
+
+| Decision | Why | What it costs |
+| --- | --- | --- |
+| Read-only over taskflow persistence as the primary source | Monitors existing deployments untouched | Resolution is the poll interval; anything entered and left between two polls was never observable |
+| Hand-rolled ASGI and WSGI callables, no web framework | Maximum embeddability: a service does not inherit Starlette because it wanted monitoring | Two implementations to keep identical, which is what the conformance suite is for |
+| Both callables ship, rather than one plus a bridge | No `a2wsgi`-style shim in either direction | -- |
+| Mountable at any sub-path, plus native adapters in `contrib/` | Standalone `serve` is one deployment mode, not the only one | Every link has to be built from a discovered prefix |
+| oslo.config for configuration | What OpenStack operators expect; the service configures the meter in the file it already reads | -- |
+| Completion derived from state, never from raw `progress` | taskflow sets progress to 1.0 on `REVERTED` as well as `SUCCESS`, so a mean of `progress` reports a fully reverted flow as complete | Two numbers in the payload instead of one |
+
+## 3. The emit side must never hurt the flow
+
+The rule the whole in-process path rests on: **nothing monitoring does can
+change a flow's outcome or its timing measurably.** Concretely:
+
+- A publisher that raises is counted and logged, and the next batch is still
+  attempted. It cannot propagate into the engine.
+- Delivery happens on its own thread behind a **bounded** queue, so a task
+  never waits on a publisher. Blocking would stall the flow; growing without
+  limit would take the process down later, for a reason nobody would connect
+  back to monitoring.
+- A full queue drops the oldest events, counts the drops, and logs. Losing
+  old monitoring data beats losing the process.
+- A listener whose callback raises logs and carries on, and the flow finishes
+  normally.
+
+The receiving side makes the opposite trade, deliberately: a handler that
+fails leaves the batch on the broker rather than acknowledging it. Silently
+dropping monitoring data is worse than redelivering it.
+
+## 4. Embedding into somebody else's application
+
+Three ways in, in increasing order of how much the host is involved:
+
+1. **Mount the raw callable.** Works in anything that can mount an ASGI or
+   WSGI app. Nothing from this package is needed.
+2. **A native adapter** from `contrib/`. The routes are registered in the
+   host's own router, so its authentication, middleware, error handling --
+   and, for FastAPI, its OpenAPI schema -- apply to them.
+3. **Hand-wire it.** `api.routes.build_routes()` returns the route table as
+   data; register the handlers yourself.
+
+### Mount-safety
+
+- **Never trust `scope["path"]` alone.** Modern Starlette's `Mount` does not
+  rewrite `path`; it extends `root_path`. Older versions stripped `path`
+  instead. A server given `--root-path` never puts the prefix in `path` at
+  all. One rule covers all three: strip `root_path` from `path` **only when
+  it is genuinely a prefix**, otherwise use `path` unchanged. That is what
+  `api.http.split_path` does.
+- **WSGI is unambiguous.** The server or dispatcher has already split
+  `SCRIPT_NAME` from `PATH_INFO`. Route on `PATH_INFO`, build links from
+  `SCRIPT_NAME`.
+- **Links are built from the discovered prefix**, plus `X-Forwarded-Prefix`
+  when a proxy stripped one, never from a hard-coded `/api/v1`.
+- **Never mutate the host's `scope` or `environ`.** Copy first.
+
+Pecan is the awkward one: it does not rewrite `PATH_INFO`, so the mount point
+is recovered by taking the remainder off the end.
+
+### Lifecycle, without lifespan
+
+**A mounted ASGI app never receives the lifespan scope.** The host router
+handles it at the root and does not forward it to a mount. So startup cannot
+hang off lifespan alone, and `Meter` owns its own lifecycle instead:
+
+1. **Explicit, and preferred:** `meter.start()` / `meter.stop()`, or use it as
+   a context manager. A host with a lifespan of its own should call these
+   from it, or from `AppConfig.ready()`.
+2. **From lifespan**, when our ASGI app *is* the root app.
+3. **Lazily**, on the first request, with an `atexit` stop.
+
+All three are idempotent and reference-counted, so starting from a host
+lifespan *and* a first request is harmless.
+
+### Being a good citizen
+
+- No module-level singletons. Every app is a factory over a `Meter`, so two
+  meters can coexist in one process.
+- No CORS headers, no global exception handlers, no logging configuration, no
+  signal handlers. Those are the host's business.
+- `HEAD` and `OPTIONS` answered correctly.
+- An unknown path inside our own prefix returns a JSON 404 rather than
+  raising into the host.
+
+### Sync core, async edge
+
+Handlers are plain synchronous functions returning a `MeterResponse`, so WSGI
+and synchronous Django call them directly. The ASGI adapter offloads the
+blocking datasource calls with `asyncio.to_thread` -- standard library, no
+`anyio` dependency -- and feeds streams from an async generator.
+
+WebSockets are declined with a clean close rather than implemented: SSE
+already carries the stream, and it works over WSGI too.
+
+**The WSGI streaming caveat**, which deployments need to know up front: a
+synchronous WSGI worker holds one thread for as long as an SSE connection
+stays open. Use gevent or eventlet workers for streaming, or let clients poll
+`/events?since_seq=` instead.
+
+## 5. Multiple workers
+
+N API workers each constructing a polling `Meter` means N pollers on the same
+database. Two supported shapes:
+
+- `Meter(poll=True)` for single-process or embedded use.
+- `Meter(poll=False)` for API workers reading a store that a separate
+  `taskflow-meter collect` process keeps filled.
+
+With `poll=False` over a taskflow backend there is no event history, so the
+event and stream endpoints answer 501 and flow payloads omit their links --
+rather than serving an empty stream that cannot be told apart from silence.
+
+## 6. Testing
+
+The suite is built on the principle that a monitoring library which is only
+tested against mocks has tested its own assumptions. So it runs real engines
+(serial and parallel), a real sqlite logbook read from a second process, real
+Pecan, Flask, Django and FastAPI applications, a real HTTP server, a real
+kombu broker and a real oslo.messaging bus, and real alembic migrations
+checked against the models.
+
+| Tree | Subject |
+| --- | --- |
+| `tests/unit/<pkg>/test_<mod>.py` | One module, mirroring the package |
+| `tests/functional/` | A behaviour across modules, including the cross-process one |
+| `tests/integration/` | Real engines, and the collector deployment end to end |
+| `tests/conformance/` | The ASGI and WSGI callables, and all six hosts, comparing bytes |
+
+A unit test module must mirror its target or `tox -e pep8` fails on the
+test-tree check. Anything that does not target a single module belongs in one
+of the sibling trees.

{taskflow_meter-1.0.0 → taskflow_meter-1.2.0}/docs/guide.md

@@ -4,6 +4,9 @@ How to deploy it into an OpenStack service, and how to answer the two
 questions people actually have: *how far along is this flow?* and *what is it
 doing right now?*
 
+For why it is built the way it is -- what taskflow does and does not record,
+and the rules an embedded app has to obey -- see [design.md](design.md).
+
 ---
 
 ## 1. Point it at a taskflow backend
@@ -186,6 +189,41 @@ The queue is durable and declared on publish, so a flow that starts before the
 collector does is not a lost run. Events are keyed on `(run_id, seq)`, so a
 collector that reconnects and redelivers writes nothing twice.
 
+### Or on the bus the service already has
+
+Inside an OpenStack service, the notification bus is usually already
+configured, already monitored, and already pointed at the right broker with
+the right credentials. The oslo.messaging transport uses it rather than
+opening a connection of its own:
+
+```bash
+taskflow-meter collect --transport oslo-messaging   --url rabbit://guest@broker//   --store-url postgresql://user@host/meter
+```
+
+```python
+from taskflow_meter.transports.oslo_messaging import OsloMessagingTransport
+
+# No URL: the service's own transport_url decides.
+publisher = OsloMessagingTransport(conf=CONF)
+with attach(engine, publishers=[publisher]):
+    engine.run()
+```
+
+These go out as **notifications**, not RPC -- fire-and-forget fanout, which
+costs the flow nothing when no collector is running. They carry the
+`taskflow_meter.events` event type on the `taskflow-meter` topic, so a
+listener that also hears other traffic can pick them out. Several collectors
+sharing the default pool share one queue, and each notification is handled
+once rather than once per collector.
+
+**One difference from the AMQP transport, and it decides which to pick.** A
+notifier cannot declare the collector's queue -- the listener owns it -- and a
+broker drops what it has nothing to route to. So events published before any
+collector has *ever* run are lost. Start the collector once before the first
+flow and the queue is durable from then on; restarts cost nothing. If flows
+genuinely run before any collector exists, use the AMQP transport, which
+declares its queue on every publish.
+
 Unlike the persistence datasource, which inherits taskflow's retention, this
 store keeps what it is told until told otherwise:
 
@@ -195,7 +233,7 @@ store.prune(before=time.time() - 30 * 86400)
 
 ---
 
-## 3b. Watching from inside the process running the flow
+## 4. Watching from inside the process running the flow
 
 Everything above reads what taskflow persisted. If you control the code that
 runs the flow, attaching to the engine gets you two things reading cannot:
@@ -242,7 +280,7 @@ without limit would take the process down later for reasons nobody would
 connect back to monitoring. A publisher that raises is counted and logged,
 and the next batch is still attempted. None of it can fail a task.
 
-## 4. How far along is this flow?
+## 5. How far along is this flow?
 
 Every flow payload carries a `completion` between 0 and 1:
 
@@ -311,7 +349,7 @@ another process within one poll interval.
 
 ---
 
-## 5. What is it doing right now?
+## 6. What is it doing right now?
 
 `running_atoms` names the atoms currently executing. It is a list because
 unordered and graph flows run several at once, and it is empty between two
@@ -375,7 +413,7 @@ Two events are not flow activity and are worth handling:
 
 ---
 
-## 6. What the meter cannot tell you
+## 7. What the meter cannot tell you
 
 Worth knowing before you go looking for it: