Make documentation standalone and generalize examples

backend/scripts/bench_engine.py

@@ -6,11 +6,11 @@ arriving at a subscriber and reaching everything downstream of it. It builds a
 pipeline and an execution service in this process, so there is no HTTP, no
 container and no browser between the measurement and the engine.
 
-Three scenarios, each answering a different question:
+Four scenarios, each answering a different question:
 
 ``throttle``
-    What does a rate-limited port cost? A source publishing every 15s behind
-    seven relays, driven at the rate the house's inverter actually sends.
+    What does a rate-limited port cost? A source publishes through relays
+    while incoming readings exceed its publication rate.
     Reports cascades enqueued, node executions and bus events per injection —
     the numbers, not the wall clock, are the point.
 
@@ -119,7 +119,7 @@ def node(
 def relay(
     node_id: str, src: str, dst: str, interval: float, counters: Counters
 ) -> Node:
-    """A node that republishes what it read — the shape the house is full of.
+    """A relay node that republishes its input.
 
     ``src`` and ``dst`` are bare port names: the pipeline qualifies them with
     the flow, and the node function only ever sees ports.
@@ -238,9 +238,8 @@ def percentile(values: list[float], p: float) -> float:
 def scenario_throttle(args: argparse.Namespace) -> dict[str, Any]:
     """A rate-limited source behind relays, driven far faster than its window.
 
-    The house's shape: an inverter sending ~200 readings a minute into seven
-    relay nodes, each told to publish every 15s. What should cost seven
-    publishes a minute is what this counts.
+    Counts the work performed when rapid inputs are held by a publication
+    interval. Relay count and interval come from the benchmark arguments.
     """
     counters = Counters()
     source = node(
@@ -285,11 +284,8 @@ def scenario_throttle(args: argparse.Namespace) -> dict[str, Any]:
 def scenario_relay(args: argparse.Namespace) -> dict[str, Any]:
     """An *unlimited* source into limited relays, and one node reading them all.
 
-    The other half of the house's shape, and the one holding it at the source
-    cannot help with: the readings really do arrive, so a cascade is owed —
-    but the relays hold their outputs back, and what reads them has nothing
-    new to read. That node published 619 messages a minute off inputs that
-    changed six times.
+    Each input starts a cascade, but rate-limited relay outputs should wake
+    the consumer only when they publish a new value.
     """
     counters = Counters()
     source = node("source", lambda params: None, provides=[spec("raw")])