fix(cloud-iam): harden time and config contracts

README.md

@@ -4,7 +4,9 @@
 
 A local, file-based detection workflow lab for reviewer-verifiable telemetry and detection demos.
 
-Latest milestone: [v0.6.0 — fourth demo and config-change investigation](https://github.com/stacknil/telemetry-lab/releases/latest).
+Current focus: v1 reviewer contract stabilization for the five-demo matrix.
+
+Latest tagged release: [v0.6.0 — fourth demo and config-change investigation](https://github.com/stacknil/telemetry-lab/releases/latest).
 
 ## Reviewer Start
 

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

@@ -46,6 +46,16 @@ Every input record includes this CloudTrail-like skeleton:
 - `responseElements`
 - `eventID`
 
+Optional input fields:
+
+- `observedTime`
+
+## Time Model
+
+- `eventTime` is normalized to `event_time` and drives sorting, bounded correlation, and signal timing.
+- optional `observedTime` is preserved as `observed_time` when present, but it is not used for detection ordering.
+- committed artifacts avoid `artifact_generated_at` so the demo output remains deterministic across local reruns.
+
 AWS CloudTrail documentation describes event record contents for who made a request, the service and action, request parameters, response data, errors, source IP, user agent, Region, time, and event ID. This demo uses a synthetic subset of that shape for local review only.
 
 Reference:

demos/cloud-iam-change-investigation-demo/artifacts/investigation_report.md

@@ -9,6 +9,7 @@ It uses no live AWS account, no real account IDs, no realtime ingestion, and no
 - normalized_events: 14
 - investigation_signals: 5
 - attack_mapping_count: 5
+- time_model: eventTime is normalized to event_time; optional observedTime is preserved as observed_time but not used for detection ordering
 
 ## Signals
 

demos/cloud-iam-change-investigation-demo/artifacts/investigation_signals.json

@@ -18,6 +18,8 @@
     "evidence_events": [
       {
         "eventID": "evt-cti-001",
+        "event_time": "2026-04-07T10:00:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:00:00Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -29,6 +31,8 @@
       },
       {
         "eventID": "evt-cti-002",
+        "event_time": "2026-04-07T10:01:20Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:01:20Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -40,6 +44,8 @@
       },
       {
         "eventID": "evt-cti-003",
+        "event_time": "2026-04-07T10:03:05Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:03:05Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -87,6 +93,8 @@
     "evidence_events": [
       {
         "eventID": "evt-cti-001",
+        "event_time": "2026-04-07T10:00:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:00:00Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -98,6 +106,8 @@
       },
       {
         "eventID": "evt-cti-002",
+        "event_time": "2026-04-07T10:01:20Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:01:20Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -109,6 +119,8 @@
       },
       {
         "eventID": "evt-cti-003",
+        "event_time": "2026-04-07T10:03:05Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:03:05Z",
         "actor": "USER_A",
         "eventSource": "signin.amazonaws.com",
@@ -120,6 +132,8 @@
       },
       {
         "eventID": "evt-cti-005",
+        "event_time": "2026-04-07T10:05:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:05:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -166,6 +180,8 @@
     "evidence_events": [
       {
         "eventID": "evt-cti-006",
+        "event_time": "2026-04-07T10:08:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:08:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -209,6 +225,8 @@
     "evidence_events": [
       {
         "eventID": "evt-cti-005",
+        "event_time": "2026-04-07T10:05:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:05:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -222,6 +240,8 @@
       },
       {
         "eventID": "evt-cti-006",
+        "event_time": "2026-04-07T10:08:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:08:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -236,6 +256,8 @@
       },
       {
         "eventID": "evt-cti-007",
+        "event_time": "2026-04-07T10:10:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:10:00Z",
         "actor": "USER_A",
         "eventSource": "cloudtrail.amazonaws.com",
@@ -284,6 +306,8 @@
     "evidence_events": [
       {
         "eventID": "evt-cti-005",
+        "event_time": "2026-04-07T10:05:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:05:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -297,6 +321,8 @@
       },
       {
         "eventID": "evt-cti-006",
+        "event_time": "2026-04-07T10:08:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:08:00Z",
         "actor": "USER_A",
         "eventSource": "iam.amazonaws.com",
@@ -311,6 +337,8 @@
       },
       {
         "eventID": "evt-cti-008",
+        "event_time": "2026-04-07T10:13:00Z",
+        "observed_time": null,
         "eventTime": "2026-04-07T10:13:00Z",
         "actor": "USER_A",
         "eventSource": "ec2.amazonaws.com",

demos/cloud-iam-change-investigation-demo/artifacts/investigation_summary.json

@@ -11,6 +11,12 @@
     "security_group_ingress_opened_after_identity_change": 1
   },
   "attack_mapping_count": 5,
+  "time_model": {
+    "event_time_source": "eventTime",
+    "observed_time_source": "observedTime when present",
+    "detection_ordering": "event_time",
+    "observed_time_event_count": 0
+  },
   "boundaries": [
     "Synthetic CloudTrail-like events only",
     "No live AWS account",

demos/cloud-iam-change-investigation-demo/artifacts/normalized_cloudtrail_events.json

@@ -1,6 +1,8 @@
 [
   {
     "eventID": "evt-cti-001",
+    "event_time": "2026-04-07T10:00:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:00:00Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -26,6 +28,8 @@
   },
   {
     "eventID": "evt-cti-002",
+    "event_time": "2026-04-07T10:01:20Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:01:20Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -51,6 +55,8 @@
   },
   {
     "eventID": "evt-cti-003",
+    "event_time": "2026-04-07T10:03:05Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:03:05Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -76,6 +82,8 @@
   },
   {
     "eventID": "evt-cti-004",
+    "event_time": "2026-04-07T10:04:10Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:04:10Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -101,6 +109,8 @@
   },
   {
     "eventID": "evt-cti-005",
+    "event_time": "2026-04-07T10:05:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:05:00Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -131,6 +141,8 @@
   },
   {
     "eventID": "evt-cti-006",
+    "event_time": "2026-04-07T10:08:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:08:00Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -156,6 +168,8 @@
   },
   {
     "eventID": "evt-cti-007",
+    "event_time": "2026-04-07T10:10:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:10:00Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -180,6 +194,8 @@
   },
   {
     "eventID": "evt-cti-008",
+    "event_time": "2026-04-07T10:13:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:13:00Z",
     "actor": "USER_A",
     "identityType": "IAMUser",
@@ -219,6 +235,8 @@
   },
   {
     "eventID": "evt-cti-009",
+    "event_time": "2026-04-07T10:20:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:20:00Z",
     "actor": "ADMIN_USER",
     "identityType": "IAMUser",
@@ -243,6 +261,8 @@
   },
   {
     "eventID": "evt-cti-010",
+    "event_time": "2026-04-07T10:25:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:25:00Z",
     "actor": "ADMIN_USER",
     "identityType": "IAMUser",
@@ -273,6 +293,8 @@
   },
   {
     "eventID": "evt-cti-011",
+    "event_time": "2026-04-07T10:30:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:30:00Z",
     "actor": "ADMIN_USER",
     "identityType": "IAMUser",
@@ -298,6 +320,8 @@
   },
   {
     "eventID": "evt-cti-012",
+    "event_time": "2026-04-07T10:45:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T10:45:00Z",
     "actor": "NETWORK_ADMIN",
     "identityType": "IAMUser",
@@ -337,6 +361,8 @@
   },
   {
     "eventID": "evt-cti-013",
+    "event_time": "2026-04-07T11:00:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T11:00:00Z",
     "actor": "USER_B",
     "identityType": "IAMUser",
@@ -362,6 +388,8 @@
   },
   {
     "eventID": "evt-cti-014",
+    "event_time": "2026-04-07T11:30:00Z",
+    "observed_time": null,
     "eventTime": "2026-04-07T11:30:00Z",
     "actor": "SECURITY_AUDITOR",
     "identityType": "IAMUser",

docs/event-time-model.md

@@ -10,8 +10,8 @@ This model is informed by the OpenTelemetry Logs Data Model distinction between
 
 | Field | Meaning | Used for detection ordering? | Current repository mapping |
 | --- | --- | --- | --- |
-| `event_time` | Time the source event happened. | Yes | The default input column is named `timestamp`; configs may use `time.timestamp_col` to point at a source column such as `event_time`. |
-| `observed_time` | Time a collector, loader, or intermediary observed the event. | No, unless a demo explicitly documents fallback behavior. | Optional future input or artifact field. Current core demos do not require it. |
+| `event_time` | Time the source event happened. | Yes | The default input column is named `timestamp`; configs may use `time.timestamp_col` to point at a source column such as `event_time`. The CloudTrail-like demo normalizes source `eventTime` into `event_time`. |
+| `observed_time` | Time a collector, loader, or intermediary observed the event. | No, unless a demo explicitly documents fallback behavior. | Optional input or artifact field. The CloudTrail-like demo preserves optional source `observedTime` as `observed_time` but does not use it for ordering. |
 | `window_start` / `window_end` | Deterministic analysis interval derived from `event_time`. | Yes | Feature rows, alert rows, and dedup artifacts use these boundaries. Windows are treated as `[window_start, window_end)`. |
 | `artifact_generated_at` | Time an output artifact was rendered or written. | No | Optional provenance metadata for reports, summaries, or reviewer packs. It must not be used as event evidence. |