Add generic peak cycle detector

README.md

@@ -62,6 +62,28 @@ The current Compose file has no application service, so it deliberately does
 not pass ENLYZE credentials to TimescaleDB. A future application service should
 use `env_file: ./secrets/enlyze.env` rather than copying secrets into Compose.
 
+## Peak-cycle detection
+
+`PeakCycleDetector` is a pure calculation-domain component for roll length,
+roll weight, and comparable sawtooth/batch signals. It retains the current
+maximum and emits it only after the value is below
+`drop_ratio * current_peak` continuously for `hold_seconds`. Configuration is
+`min_peak`, `drop_ratio` (strictly between 0 and 1), non-negative
+`hold_seconds`, and positive `max_sample_gap_seconds`. The hold uses elapsed
+timestamps, never a sample count; an interval longer than the configured
+maximum sample gap restarts a reset candidate,
+so a timestamp gap alone is not evidence that a signal remained below threshold.
+`max_sample_gap_seconds` is required rather than defaulted, so the source's
+continuity assumption is explicit for each detector configuration.
+Reset values can be negative and need not be zero. Equal timestamps are
+accepted in arrival order but add no elapsed hold time; backwards timestamps
+are rejected.
+
+The first real-world validation case is K7 roll length (m), variable
+`bf81c547-dccf-4709-aee2-0f78366d1dfc`. When the ignored local capture is
+present, run `python scripts/validate_k7_roll_length.py` to inspect detected
+peaks without adding the raw capture to tests or version control.
+
 `docker compose up -d timescaledb` is an optional local database design for a
 future persistence milestone. It is not required for the bootstrap tests.