Add generic peak cycle detector

docs/architecture.md

@@ -39,3 +39,19 @@ Future calculation state is stored per calculation instance and relevant
 context partition. It enables safe continuation (for example an open peak
 cycle), while the source interval recorded on results keeps a historical run
 reproducible by fetching ENLYZE data again.
+
+## Peak-cycle semantics
+
+The generic peak detector maintains an open cycle maximum. A reset begins when
+a sample falls below `drop_ratio * current_peak`; it is confirmed only after
+actual subsequent below-threshold samples support `hold_seconds` of elapsed
+time. It emits only maxima at least `min_peak`, starts a fresh cycle after a
+completed reset, and suppresses duplicates during the continuing low phase.
+This is calculation-domain logic, with no ENLYZE transport dependency.
+
+The detector uses timestamps rather than a sample count. An interval longer
+than the configured positive `max_sample_gap_seconds` restarts a reset candidate,
+so a timestamp alone does not establish that a signal was continuously below
+threshold. Equal
+timestamps are processed in arrival order but contribute no elapsed time, and
+backwards timestamps are rejected. Reset values are not assumed to be zero.

docs/roadmap.md

@@ -26,12 +26,12 @@ Implement one configured integration calculation over a verified signal and
 production-order context. Include backfill, rerun/provenance behavior, and
 tests against sanitized fixtures.
 
-## 4. Peak detection
+## 4. Peak detection (first detector completed)
 
-Implement the configurable sawtooth peak detector: retain the current maximum;
-close a cycle after a configurable below-peak fraction remains true for a
-configurable duration; emit one completed peak event; preserve open-cycle
-state.
+The generic configurable sawtooth detector is implemented: it retains the
+current maximum, closes a cycle after a configurable below-peak fraction has
+actual sample support for a configurable elapsed duration, and emits one
+completed peak. Its pure state can later be persisted for incremental use.
 
 ## Later