Skip to main content

Aggregate processing

Scope​

This page defines windowed aggregate processing for outcome events.

Aggregate processing groups historical events and emits one rating per group when an aggregate policy matches.

Grouping model​

A group is formed by:

  • billing_user_id
  • parent billing_account_id
  • resolved contract as-of each event
  • day window (window_start, window_end)
  • event_type

Only semantic_kind='outcome' events participate in this flow.

Eligibility window​

Aggregate processing is applied to closed historical windows.

Practical effect:

  • recent windows are intentionally deferred
  • finalized historical windows are grouped and rated

Candidate policy rules​

  • only active policy versions effective at window_start
  • engine must be aggregate
  • event type must match exactly

If zero or multiple policies match a group, no aggregate rating is emitted for that group.

Aggregate metric rules​

count is always available.

Additional aggregate keys are computed from DSL aggregate expressions:

  • payload fields
  • label fields
  • selected event fields

Numeric aggregates (sum/avg/min/max) ignore non-numeric values by producing null for non-numeric inputs.

Contract param rules​

  • required DSL params are resolved from contract terms as-of window_start
  • missing or invalid required params defer rating for that group until data is fixed

Emission rules​

For each eligible group:

  • exactly one evaluated intent is required
  • one rating is emitted from that intent
  • one aggregation-run record is persisted

Linking back to raw events​

When event-linking is enabled in deployment policy:

  • emitted group rating is linked to each member event in the grouped window
  • links are idempotent and conflict-safe

Idempotency and uniqueness​

Aggregate outputs are idempotent by window/group/policy identity.

Re-sweeping the same closed group reuses existing run identity and avoids duplicate rating effects.

Verify checklist​

  • Closed windows produce one stable aggregate rating per unique group.
  • Re-running sweep does not duplicate ratings.
  • Missing contract params defer emission until params are available.
  • Event-to-rating links exist when link mode is enabled.