docs(contract): define bounded correlation

README.md

@@ -14,7 +14,7 @@ Latest tagged release: [v0.6.0 — fourth demo and config-change investigation](
 - [`docs/reviewer-path.md`](docs/reviewer-path.md): choose the right demo by review question
 - [`docs/reviewer-pack.md`](docs/reviewer-pack.md): demo matrix, artifact contract, and v1 readiness gate
 - [`docs/evidence-pipeline-contract.md`](docs/evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts
-- [`docs/vocabulary.md`](docs/vocabulary.md): cross-demo vocabulary for events, hits, signals, findings, summaries, reports, and audit traces
+- [`docs/vocabulary.md`](docs/vocabulary.md): cross-demo vocabulary for events, hits, signals, bounded correlation, findings, summaries, reports, and audit traces
 - [`docs/README.md`](docs/README.md): current route, supporting docs, and historical release evidence
 
 ## Demos
@@ -171,7 +171,7 @@ Cooldown behavior:
 - [`docs/reviewer-path.md`](docs/reviewer-path.md) maps common review questions to the right demo and artifacts
 - [`docs/architecture.md`](docs/architecture.md) diagrams the local file-based detection workflow
 - [`docs/event-time-model.md`](docs/event-time-model.md) defines event, observed, window, and artifact time semantics
-- [`docs/vocabulary.md`](docs/vocabulary.md) defines the cross-demo evidence workflow terms
+- [`docs/vocabulary.md`](docs/vocabulary.md) defines the cross-demo evidence workflow terms and bounded correlation boundaries
 - [`docs/sample-output.md`](docs/sample-output.md) summarizes the committed sample artifacts
 - [`docs/roadmap.md`](docs/roadmap.md) defines the v1 reviewer contract stabilization phase
 - [`data/processed/summary.json`](data/processed/summary.json) captures the default run in machine-readable form

demos/cloud-iam-change-investigation-demo/README.md

@@ -72,6 +72,11 @@ The deterministic rules are:
 - CloudTrail logging disabled near IAM change
 - security group ingress opened after identity change
 
+Each rule uses bounded correlation: evidence must fall inside the rule's fixed
+time window, match the rule's configured actor or entity scope, and match the
+rule-local event family set. The demo does not perform cross-account,
+cross-source, or whole-dataset attribution.
+
 ## ATT&CK Mapping
 
 The config intentionally keeps the mapping set small:

demos/config-change-investigation-demo/README.md

@@ -50,6 +50,9 @@ Evidence is attached only when:
 
 1. `target_system` matches the triggering change
 2. the evidence timestamp falls within the configured correlation window after the change
+3. the evidence family is one of the configured local evidence families for this demo
+
+It does not perform cross-host, cross-account, or cross-source global attribution.
 
 ## Expected Artifacts
 

docs/README.md

@@ -8,7 +8,7 @@ This directory separates the current reviewer route from supporting design notes
 - [`reviewer-path.md`](reviewer-path.md): choose a demo by review question
 - [`reviewer-brief.md`](reviewer-brief.md): short problem, value, evidence, and boundary summary
 - [`evidence-pipeline-contract.md`](evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts
-- [`vocabulary.md`](vocabulary.md): cross-demo vocabulary for evidence workflow terms
+- [`vocabulary.md`](vocabulary.md): cross-demo vocabulary for evidence workflow terms and bounded correlation
 - [`architecture.md`](architecture.md): local file-based workflow diagram
 - [`roadmap.md`](roadmap.md): v1 reviewer contract stabilization phase
 

docs/architecture.md

@@ -32,6 +32,7 @@ flowchart TD
 
 - Detection decisions stay deterministic and inspectable.
 - The AI-assisted demo is limited to bounded JSON-only case drafting.
+- Bounded correlation stays inside fixed time windows, fixed entity or scope keys, and fixed event families or rule-local family sets.
 - Artifacts are file-based and suitable for local regeneration or GitHub review.
 - Artifact names are reviewer-visible contracts during the v1 reviewer contract stabilization phase.
 - The repository does not provide production monitoring, real-time ingestion, dashboards, alert routing, case management, autonomous response, or final incident verdicts.

docs/reviewer-pack.md

@@ -43,6 +43,8 @@ See [`docs/evidence-pipeline-contract.md`](evidence-pipeline-contract.md) for th
 
 See [`docs/vocabulary.md`](vocabulary.md) for the cross-demo meaning of `event`, `signal`, `hit`, `finding`, `case_bundle`, `summary`, `report`, and `audit_trace`.
 
+In this repo, bounded correlation means evidence is attached only within fixed time windows, fixed entity or scope keys, and fixed event families or rule-local family sets. It is not cross-host, cross-account, or cross-source global attribution.
+
 The current schema contract covers:
 
 - `schemas/rule_hits.schema.json`

docs/vocabulary.md

@@ -42,6 +42,22 @@ keeps the repo focused on reproducible evidence generation and review.
 - Use `report` for human-readable Markdown explanations.
 - Use `audit_trace` for structured guardrail, validation, and provenance records.
 
+## Bounded Correlation
+
+`bounded correlation` means the demo may attach supporting evidence only inside
+explicitly configured limits:
+
+- a fixed time window
+- a fixed entity or scope key, such as `target_system`, `actor`, `account`, or
+  resolved cooldown scope
+- a fixed event family, or a rule-local configured family set when a rule
+  intentionally compares more than one event family
+
+It does not perform global attribution across hosts, accounts, sources, or event
+families. It does not infer a shared root cause from unrelated telemetry, search
+the whole dataset for plausible context, or promote nearby evidence into a final
+incident verdict.
+
 ## Time Semantics
 
 Events, hits, signals, summaries, and reports should preserve the time semantics

tests/test_reviewer_docs.py

@@ -251,6 +251,11 @@ def test_vocabulary_defines_cross_demo_terms() -> None:
     assert "local evidence workflow vocabulary" in vocabulary
     assert "not a SIEM object model" in vocabulary
     assert "[`docs/event-time-model.md`](event-time-model.md)" in vocabulary
+    assert "## Bounded Correlation" in vocabulary
+    assert "fixed time window" in vocabulary
+    assert "fixed entity or scope key" in vocabulary
+    assert "fixed event family" in vocabulary
+    assert "does not perform global attribution across hosts, accounts, sources" in vocabulary
 
     for term in [
         "event",
@@ -273,6 +278,25 @@ def test_vocabulary_defines_cross_demo_terms() -> None:
     assert "Keep cross-demo vocabulary stable" in roadmap
 
 
+def test_bounded_correlation_boundaries_are_documented() -> None:
+    architecture = _read_repo_file("docs/architecture.md")
+    reviewer_pack = _read_repo_file("docs/reviewer-pack.md")
+    config_demo = _read_repo_file("demos/config-change-investigation-demo/README.md")
+    cloud_iam_demo = _read_repo_file(
+        "demos/cloud-iam-change-investigation-demo/README.md"
+    )
+
+    for text in [architecture, reviewer_pack]:
+        assert "fixed time windows" in text
+        assert "fixed entity or scope keys" in text
+        assert "fixed event families or rule-local family sets" in text
+
+    assert "evidence family" in config_demo
+    assert "cross-host, cross-account, or cross-source global attribution" in config_demo
+    assert "rule-local event family set" in cloud_iam_demo
+    assert "whole-dataset attribution" in cloud_iam_demo
+
+
 def test_architecture_doc_keeps_local_file_based_boundaries() -> None:
     architecture = _read_repo_file("docs/architecture.md")