Retain distinct same-time events with stable identity and honest order semantics

.capabilities/data/quality/analyze-sparse-observations.capability.yaml

@@ -21,6 +21,8 @@ guidance:
   - Default missingness is unknown. A modeled expectation is never a measurement.
   - Caller business severity, incident state and notifications remain outside
     the engine.
+  - Optional event-identity-v1 IDs retain simultaneous distinct calls; only a
+    separately asserted trusted sequence permits ordering their measurements.
 planning:
   story_map:
     backbone: Monitor while periods are still open

.capabilities/data/quality/prepare-timestamped-series.capability.yaml

@@ -9,15 +9,18 @@ acceptance:
     without a calendar frequency.
   - Local timestamps require a timezone, and ambiguous or nonexistent
     daylight-saving times require an explicit offset.
-  - Duplicate timestamps are rejected unless an aggregation policy is supplied;
-    duplicate counts and transformations remain visible.
+  - Calendar duplicate timestamps require an aggregation policy; identified
+    event-index calls can share original timestamps while duplicate logical IDs
+    are rejected and arbitrary tie order supplies no sequence evidence.
   - An as_of cutoff excludes later observations, and cadence is checked as a
     fixed elapsed duration.
 guidance:
   - No interpolation or implicit filling, resampling, or unit conversion occurs.
     Schema-1.1 source policies may explicitly authorize confirmed empty additive
     volume as zero.
   - Duplicate null values propagate through aggregation.
+  - Stable event identity and trusted sequence are separate caller contracts;
+    legacy event inputs without IDs still require unique timestamps.
 planning:
   story_map:
     backbone: Analyze a local series
@@ -37,6 +40,9 @@ agent:
   # -----------------------------
   implementation:
     references:
+      - src/anomalyzer/events.py
+      - tests/test_events.py
+      - docs/sparse-data.md
       - src/anomalyzer/sparse.py
       - tests/test_sparse.py
       - src/anomalyzer/validation.py
@@ -57,6 +63,7 @@ agent:
           cutoff.
         command: python -m pytest -q
           tests/test_analysis.py::test_duplicate_sort_and_cutoff
+          tests/test_events.py::test_distinct_same_time_calls_keep_values_references_and_cases
       - id: cadence-context
         description: Check fixed weekly cadence and preserve cutoff semantics across
           interfaces.

.capabilities/interfaces/python/install-versioned-library.capability.yaml

@@ -72,9 +72,6 @@ agent:
       - Follow the release guide and confirm Guard retains domain severity and
         incident ownership; inspect readiness and evidence limits before
         adopting.
-    gaps:
-      - First immutable GitHub Release requires owner setup and a reviewed
-        version tag.
   review:
     depth: partial
     source: deterministic-assessment
@@ -112,26 +109,29 @@ agent:
           - scripts/release.py:39
           - scripts/release.py:48
           - scripts/release.py:54
-          - scripts/publish_release.py:19
-          - scripts/publish_release.py:27
-          - scripts/publish_release.py:29
-          - scripts/publish_release.py:39
-          - scripts/verify_lambda.sh:14
-          - scripts/verify_lambda.sh:17
-          - scripts/verify_lambda.sh:19
-          - scripts/verify_lambda.sh:25
-          - scripts/verify_lambda.sh:27
+          - scripts/publish_release.py:21
+          - scripts/publish_release.py:34
+          - scripts/publish_release.py:42
+          - scripts/publish_release.py:53
+          - scripts/verify_lambda.sh:15
+          - scripts/verify_lambda.sh:18
+          - scripts/verify_lambda.sh:20
+          - scripts/verify_lambda.sh:26
+          - scripts/verify_lambda.sh:28
+          - examples/library/guard_smoke.py:74
           - .github/workflows/ci.yml:14
           - .github/workflows/ci.yml:19
           - .github/workflows/ci.yml:27
-          - .github/workflows/ci.yml:41
-          - .github/workflows/ci.yml:46
-          - .github/workflows/release.yml:28
-          - docs/releases/README.md:12
-          - docs/releases/README.md:13
-          - docs/releases/README.md:14
+          - .github/workflows/ci.yml:43
+          - .github/workflows/ci.yml:48
+          - .github/workflows/release.yml:31
+          - .github/workflows/release.yml:52
+          - .github/workflows/release.yml:61
+          - docs/releases/README.md:16
           - docs/releases/README.md:17
           - docs/releases/README.md:18
+          - docs/releases/README.md:21
+          - docs/releases/README.md:22
           - tests/test_release.py:60
           - tests/test_release.py:71
           - tests/test_release.py:81
@@ -145,17 +145,19 @@ agent:
         status: partial
         evidence:
           - scripts/verify_distribution.py:1
-          - scripts/verify_distribution.py:42
+          - scripts/verify_distribution.py:48
           - examples/library/guard_smoke.py:32
           - examples/library/guard_smoke.py:49
           - examples/library/guard_smoke.py:65
           - examples/library/guard_smoke.py:69
-          - examples/library/guard_smoke.py:75
-          - .github/workflows/ci.yml:57
-          - docs/releases/README.md:13
-          - docs/releases/README.md:208
-          - docs/releases/README.md:211
-          - docs/releases/README.md:213
+          - examples/library/guard_smoke.py:76
+          - .github/workflows/ci.yml:59
+          - .github/workflows/release.yml:60
+          - docs/releases/README.md:17
+          - docs/releases/README.md:99
+          - docs/releases/README.md:217
+          - docs/releases/README.md:220
+          - docs/releases/README.md:222
         notes: Related implementation text was found, but deterministic matching cannot
           prove the behavior. Review the cited evidence. If it is correct, save
           agent.review evidence or make the criterion/reference wording more
@@ -173,27 +175,28 @@ agent:
           - scripts/release.py:85
           - scripts/release.py:92
           - scripts/publish_release.py:1
-          - scripts/publish_release.py:25
-          - scripts/publish_release.py:26
-          - scripts/publish_release.py:27
-          - scripts/publish_release.py:28
-          - scripts/verify_distribution.py:41
-          - scripts/verify_lambda.sh:24
+          - scripts/publish_release.py:18
+          - scripts/publish_release.py:19
+          - scripts/publish_release.py:20
+          - scripts/publish_release.py:40
+          - scripts/verify_distribution.py:47
+          - scripts/verify_lambda.sh:25
           - examples/library/guard_smoke.py:39
-          - .github/workflows/ci.yml:42
-          - .github/workflows/ci.yml:45
-          - .github/workflows/ci.yml:46
-          - .github/workflows/ci.yml:49
+          - .github/workflows/ci.yml:44
+          - .github/workflows/ci.yml:47
+          - .github/workflows/ci.yml:48
           - .github/workflows/ci.yml:51
-          - .github/workflows/release.yml:31
-          - .github/workflows/release.yml:33
+          - .github/workflows/ci.yml:53
+          - .github/workflows/release.yml:34
           - .github/workflows/release.yml:36
-          - .github/workflows/release.yml:37
-          - docs/releases/README.md:3
-          - docs/releases/README.md:12
-          - docs/releases/README.md:14
-          - docs/releases/README.md:15
+          - .github/workflows/release.yml:39
+          - .github/workflows/release.yml:40
+          - .github/workflows/release.yml:48
+          - docs/releases/README.md:8
+          - docs/releases/README.md:16
+          - docs/releases/README.md:18
           - docs/releases/README.md:19
+          - docs/releases/README.md:23
           - tests/test_release.py:1
           - tests/test_release.py:21
           - tests/test_release.py:23
@@ -211,21 +214,22 @@ agent:
           - pyproject.toml:33
           - scripts/release.py:81
           - scripts/release.py:82
-          - scripts/publish_release.py:40
-          - scripts/verify_distribution.py:41
+          - scripts/publish_release.py:54
+          - scripts/verify_distribution.py:47
           - scripts/verify_lambda.sh:6
-          - scripts/verify_lambda.sh:17
-          - scripts/verify_lambda.sh:19
-          - .github/workflows/ci.yml:30
-          - .github/workflows/ci.yml:31
-          - .github/workflows/ci.yml:51
-          - .github/workflows/ci.yml:52
-          - .github/workflows/ci.yml:90
-          - docs/releases/README.md:12
-          - docs/releases/README.md:15
-          - docs/releases/README.md:58
-          - docs/releases/README.md:59
-          - docs/releases/README.md:75
+          - scripts/verify_lambda.sh:18
+          - scripts/verify_lambda.sh:20
+          - .github/workflows/ci.yml:29
+          - .github/workflows/ci.yml:32
+          - .github/workflows/ci.yml:33
+          - .github/workflows/ci.yml:53
+          - .github/workflows/ci.yml:54
+          - .github/workflows/release.yml:62
+          - docs/releases/README.md:16
+          - docs/releases/README.md:19
+          - docs/releases/README.md:62
+          - docs/releases/README.md:63
+          - docs/releases/README.md:79
         notes: Related implementation text was found, but deterministic matching cannot
           prove the behavior. Review the cited evidence. If it is correct, save
           agent.review evidence or make the criterion/reference wording more

README.md

@@ -30,7 +30,7 @@ For application builds without a source checkout, use a pinned wheel from
 [GitHub Releases](https://github.com/PredictabilityAtScale/anomaly-detection/releases).
 The [release and library-consumer guide](docs/releases/README.md) explains the
 first release, dependency hashes, upgrades and Linux/Python 3.12 bundling for Guard.
-Version 0.2.1 includes the sparse-data progression in chapters 14–22. Tagged
+Version 0.3.0 includes the sparse-data progression in chapters 14–24. Tagged
 artifacts are published after the workflow passes and the owner seals the draft.
 
 Install from a checkout with Python 3.11–3.13:
@@ -193,7 +193,7 @@ when visualization is unavailable.
 Schema 1.0 is the single-series contract. Schema 1.1 adds named datasets,
 relationships, assessments, policy, and cases; it also works with one dataset
 and no relationships. Both use the same analysis core through CLI, Python, and
-MCP. Sparse schema-1.1 and multi-resolution support is described in chapters 14–22.
+MCP. Sparse schema-1.1, multi-resolution and identified events are described in chapters 14–24.
 The legacy schema-1.0 multi-resolution profile does
 not support `reset_points`; both other recipes support explicit resets.
 
@@ -730,6 +730,54 @@ the remaining complete-span restrictions. All new fixtures run through
 `examples/run_demo.py`; the existing generator and figure renderer reproduce the
 full progression.
 
+### 23. Keep distinct calls at the same recorded time
+
+Two completed calls can share the exact timestamp while having different costs.
+The [identified-call example](examples/sparse/identified_calls.json) supplies
+aligned `event_ids` under `data_policy.observation_basis="event_index"`.
+It retains all ten original calls: three in the training cohort, four in the
+calibration cohort, and three at `09:00:10.789Z`. The last three cost $0.80,
+$0.12 and $0.90. They remain three observations at the same time; no jitter,
+averaging or delivery order is introduced.
+
+![Distinct call costs at exact shared timestamps, with separate IDs and a frozen prior-time reference](docs/images/anomaly-progression-23-same-time-calls.png)
+
+The $0.80 and $0.90 calls each have inspectable point/range evidence and a distinct
+`Case.event_id`. A whole timestamp cohort finishes training or calibration before
+a later cohort can use that reference; alphabetical ID order never trains one
+same-time call on another. Actual support can therefore exceed the requested
+minimum training/calibration count. Event IDs and source indexes link evidence
+back to the original measurements. Separate findings do not imply separate
+notifications or independent confirmations.
+
+### 24. Declare identity, retries and order separately
+
+`event-identity-v1` requires caller-trusted logical IDs. A retry keeps the same
+ID; the [duplicate-delivery fixture](examples/sparse/identified_retry.json) is
+rejected instead of counted as another call. Repeating a valid snapshot preserves
+its case and evidence IDs. The [correction fixture](examples/sparse/identified_corrected.json)
+addresses `call-07` using `SampleRevision.event_id`, keeps its original timestamp,
+and changes its case revision while retaining the case ID. The
+[earlier as-of snapshot](examples/sparse/identified_before_correction.json) still
+returns the original evidence.
+
+![Identical same-time residuals support points but no timestamp-only sequence pattern; an explicit trusted sequence permits order-based checks](docs/images/anomaly-progression-24-event-order.png)
+
+In the [timestamp-only example](examples/sparse/identified_pattern_ties.json),
+twelve comparable evaluation calls share one timestamp. Their point reference
+is usable, but their ID layout cannot establish change-rule, Nelson, CUSUM or
+moving-range continuity. Each tied call breaks those comparisons. There is no
+sequence-pattern case in this example.
+
+The [ordered variant](examples/sparse/identified_pattern_sequence.json) adds
+`data_policy.event_order="trusted_sequence"` and unique aligned integer
+`event_sequence` ordinals. Only a caller with an actual trustworthy ordering
+contract should assert that order. The same timestamps stay unchanged; the
+declared sequence permits residual pattern checks without establishing elapsed
+rates, causal explanation or independence. Without IDs, the existing unique-time
+event-index contract continues unchanged. See the [API guide](docs/sparse-data.md#stable-event-identities-since-030)
+for validation, replay, alignment and caller responsibilities.
+
 ## Baseline and calibration reference
 
 The robust expectation for sample `t` uses four previous matching seasonal

docs/releases/0.3.0.md

@@ -0,0 +1,48 @@
+# Anomalyzer 0.3.0 — distinct events at the same original time
+
+Schema 1.1 adds the optional `event-identity-v1` contract for comparable event-index
+measurements. `DatasetV11.event_ids` retain distinct same-time calls without
+jitter, aggregation or lost values. Repeated logical IDs are rejected, including
+identical retry deliveries; callers own trustworthy identity and upstream deduplication.
+
+- Default `data_policy.event_order="timestamp"` sorts time/ID for layout only.
+  Whole timestamp cohorts finish training/calibration before a later timestamp
+  uses the reference. Tied observations keep point and explicit range evidence,
+  break change comparisons, and cannot create sequence-pattern continuity.
+- Optional `event_order="trusted_sequence"` requires aligned unique integer
+  `event_sequence` ordinals consistent with nondecreasing original times. This
+  is a caller assertion of order, not independence, causation or elapsed cadence.
+- `SampleRevision.event_id` addresses a correction to one existing event at its
+  original time. Availability/as-of selection is deterministic. Case and evidence
+  IDs use logical identity; relevant changes create a new case revision. Cases,
+  point episodes and rule findings can overlap and are not alert counts.
+- Assessments/cases expose `event_id`; quality samples preserve original time,
+  original input index, initial value and selected revision provenance. MCP
+  `get_evidence.source_samples` makes distinct same-time calls inspectable.
+- Exact identified relationships require matching logical identities and order
+  contracts. Lineage exposes source event IDs and original timestamp strings.
+  Unordered tied events cannot feed a lagged relationship.
+- README chapters 23–24 continue the existing numbered progression with six
+  reproducible fixtures and two rendered charts. Source tests cover schemas,
+  Python, CLI, MCP, prefix/as-of/corrections and bounded result growth. Installed
+  artifact checks and the offline Linux x86_64/Python 3.12 consumer exercise IDs.
+- The standalone Linux benchmark includes 1,344 distinct calls with four per
+  timestamp. Its result sizes and warm timings are mechanics checks, not measured
+  production capacity, accuracy, memory consumption or cold-start cost.
+- Release staging retries reads after draft creation to tolerate GitHub's draft
+  index delay without creating or overwriting another release.
+
+Calendar grids and legacy unique-time event inputs keep their existing numerical
+semantics; schema 1.0 remains unchanged. Upgrade strict schema-1.1 readers/producers
+together for the added fields. The package remains alpha, supports Python 3.11–3.13,
+and is distributed as an immutable GitHub wheel/sdist with hash-pinned dependencies.
+
+Limits: the engine cannot authenticate event IDs/order, detect aliases, maintain
+a durable retry/arrival ledger, infer independence, or finalize an open same-time
+cohort. Adding a newly available member/correction can revise later references;
+explicit availability preserves earlier as-of snapshots. Event-index calendar
+aggregation, multi-seasonality and business incident/notification policy remain
+outside this contract. This release does not change or deploy UsageTap Guard.
+
+See `docs/sparse-data.md`, README chapters 23–24 and `docs/releases/README.md` for
+the exact API, replay boundaries, examples and Linux build-time installation.