feat(detector): emit time-separated detection episodes

Author: stacknil

CHANGELOG.md

@@ -10,15 +10,18 @@ All notable user-visible changes should be recorded here.
 
 ### Changed
 
-- None yet.
+- Detector rules now emit separate findings for time-separated detection
+  episodes within the same rule subject instead of collapsing each subject to a
+  single best window.
 
 ### Fixed
 
 - None yet.
 
 ### Docs
 
-- None yet.
+- Documented detection episode semantics in the rule catalog and report artifact
+  contract notes.
 
 ## v0.5.0
 

README.md

@@ -84,6 +84,11 @@ LogLens currently detects:
 - One IP trying multiple usernames within 15 minutes
 - Bursty sudo activity from the same user within 5 minutes
 
+Each rule can emit multiple findings for the same subject when matching
+evidence appears in time-separated detector episodes. Report consumers should
+use `window_start`, `window_end`, and `evidence_event_ids` rather than assuming
+one finding per `rule_id` and subject.
+
 LogLens currently parses and reports these additional auth patterns beyond the core detector inputs:
 
 - `Accepted publickey` SSH successes

docs/report-artifacts.md

@@ -61,6 +61,11 @@ fixtures explicitly.
 
 `evidence_event_ids` are deterministic local event identifiers derived from the source line number, formatted as `line:<number>`. They let reviewers trace a finding back to the normalized input events that satisfied the rule window without implying global event identity.
 
+Consumers should not assume that `rule_id` plus `subject` is unique within a
+report. A rule can emit multiple findings for the same subject when matching
+evidence appears in time-separated detector episodes. Use `window_start`,
+`window_end`, and `evidence_event_ids` to distinguish episode-level findings.
+
 `verdict_boundary` is a stable token that states what the finding must not be
 read as. It keeps machine-readable findings aligned with LogLens's triage
 scope:

docs/rule-catalog.md

@@ -26,6 +26,29 @@ Metadata equivalent:
 - Default values below match the built-in detector configuration.
 - The checked-in `assets/sample_config.json` is a tested default-equivalent fixture.
 
+## Detection Episode Semantics
+
+Within each rule grouping key, LogLens sorts matching signals by timestamp and
+source line number. Consecutive signals separated by an idle gap greater than
+the rule window start a new episode candidate.
+
+Inside each episode candidate, the detector keeps the best sliding window for
+the rule:
+
+- `brute_force` and `sudo_burst`: highest event count
+- `multi_user_probing`: highest distinct username count, with event count as
+  the tie-breaker
+
+Each episode candidate that reaches the configured threshold emits one finding.
+The same `rule_id` and `subject` can therefore appear more than once in one
+report when the evidence contains time-separated bursts. Review
+`window_start`, `window_end`, and `evidence_event_ids` to distinguish those
+episodes.
+
+Episode splitting is a detector reporting model, not an incident boundary. It
+does not infer compromise, attribution, causality between rules, or cross-host
+correlation.
+
 ## Finding Explainability Fields
 
 JSON findings include both the finding conclusion and the rule context used to reach it:
@@ -89,7 +112,7 @@ Signals without a source IP are not grouped for this rule.
 
 10 minutes by default.
 
-The detector uses a sliding timestamp window within each source-IP group.
+The detector uses the episode semantics above within each source-IP group.
 
 ### Threshold
 
@@ -155,7 +178,7 @@ Signals without a source IP are not grouped for this rule. Distinct username cou
 
 15 minutes by default.
 
-The detector uses a sliding timestamp window within each source-IP group.
+The detector uses the episode semantics above within each source-IP group.
 
 ### Threshold
 
@@ -224,7 +247,7 @@ Signals without a username are not grouped for this rule.
 
 5 minutes by default.
 
-The detector uses a sliding timestamp window within each username group.
+The detector uses the episode semantics above within each username group.
 
 ### Threshold