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")])

backend/scripts/bench_startup.py

@@ -1,13 +1,7 @@
-"""How long it takes to get a run started, which is the thing Kedro is slow at.
+"""Measure submission and completion latency against a running engine.
 
-A pipeline framework that boots the project per run pays that cost every time:
-``kedro run`` on a pipeline that does nothing takes about a second, and a sweep
-of five hundred configs therefore spends ten minutes doing nothing. Fluksio
-answers that by not booting anything — the engine is already up and its workers
-already have the code loaded, so submitting is one request.
-
-This measures that claim against a running stack, so it can be checked rather
-than asserted. Run it with the dev stack up::
+Uses a no-op flow to isolate scheduling overhead. Optionally compare it with
+an empty Kedro pipeline on the same machine. Run with the dev stack up::
 
     make bench-startup
     make bench-startup BENCH_ARGS="--runs 50 --kedro ../path/to/kedro/project"

backend/scripts/soak.py

@@ -12,9 +12,8 @@ the work queue — and then takes pieces of the stack away to see what survives.
 The redis scenario, which `all` includes, needs `--force`: the Redis it stops
 is the one the whole stack journals to, not a copy of its own.
 
-Every docker verb goes through :func:`docker`, which refuses any container that
-is not part of this project's compose stack. The machine this runs on hosts
-unrelated services; nothing here may ever reach them.
+Every Docker command goes through :func:`docker`, which limits operations to
+containers in this project's Compose stack.
 
 The engine's semantic is latest-value-wins with cascades running concurrently,
 so counter equality is not a promise and is not asserted. What is asserted is