Skip to main content

Event rating policies lifecycle

This guide defines lifecycle semantics and governance rules for Event -> Rating policy management.

Mental model​

  • Policy (event_rating_policies) is the governance object.
  • Version (event_rating_policy_versions) is the executable rating rule snapshot.
  • Runtime behavior depends on version status + effective time, not on creation order.

Policy object rules​

  • policy_id must be a valid slug-like identifier.
  • Policy statuses: active or disabled.
  • Disabled policy cannot receive active versions.
  • Policy deletion requires policy status to be disabled.

Version object rules​

  • Version statuses: draft, active, deprecated.
  • Version key is (policy_id, policy_version).
  • effective_at is required.
  • A policy cannot have two versions with the same effective_at.

Mutability and immutability​

  • Only draft versions are mutable.
  • Only draft versions are deletable.
  • Updating or deleting non-draft versions returns conflict behavior.
  • Reusing the same policy_version with different DSL hash is a conflict.

Effective version selection at runtime​

For a given policy and event business time:

  • choose versions with status='active'
  • keep versions with effective_at <= event time
  • pick the latest by effective_at

This selection is time-based and deterministic.

Why DSL validate endpoint matters​

Validation is not syntax-only. It enforces runtime dependencies:

  • referenced features exist
  • referenced meters exist
  • meter semantic kind matches outcome billing requirements
  • feature-meter links exist

Without this gate, a syntactically valid DSL can still fail operationally.

Validation output semantics​

Validation returns:

  • valid flag
  • computed_dsl_hash
  • summary metadata:
    • DSL version
    • engine
    • match event type
    • required contract term keys
    • referenced features and meters
    • expected meter semantic kind
  • typed error list when invalid

Common validation failure families​

  • dsl_invalid
  • feature_missing
  • meter_missing
  • meter_semantic_kind_invalid
  • feature_meter_unmapped

Safe rollout pattern​

  1. Keep policy active, create version as draft.
  2. Validate DSL against current realm objects.
  3. Promote version only when dependent features/meters are ready.
  4. Deprecate old versions after observation period.
  5. Disable policy before destructive cleanup.

Common production pitfalls​

  • Promoting a version before feature-meter mapping is deployed.
  • Treating policy_version as editable tag.
  • Deleting policy while still enabled.

Next​