Skip to main content

Rating traceability

This guide defines a repeatable trace method across billing entities for incident response and support evidence.

Trace chain​

  • Event: source fact captured at ingest boundary.
  • Rating: pricing/cost decision snapshot.
  • Rated record: per-meter decomposition of rating.
  • Allocation: funding application and settlement state.
  • Attribution (where available): business ownership mapping for rating.

Join keys and linkage rules​

  • rated_record.rating_id -> rating.rating_id
  • allocation.rating_id -> rating.rating_id
  • allocation.reversal_of_allocation_id -> prior allocation.allocation_id (reversal chain)
  • rating.reversal_of_rating_id -> prior rating.rating_id
  • attribution.rating_id -> rating.rating_id

Use ids above as authoritative joins for incident evidence.

Cardinality expectations​

  • One event can lead to zero, one, or multiple ratings.
  • One rating can contain multiple rated records.
  • One rating can map to multiple allocations (for example split funding or reversals).
  • One rating can have multiple attribution rows.

Query defaults that affect trace outcomes​

  • Ratings list defaults to sort_by=rated_at, sort_order=desc.
  • Rated-records list defaults to sort_by=created_at, sort_order=desc.
  • Allocations list defaults to sort_by=rated_at, sort_order=desc.
  • allocations.expand=rating inlines rating.
  • allocations.expand=rating.rated_records inlines both rating and rated records.
  • ratings.expand=rated_records inlines decomposition records for direct rating inspection.

Investigation playbook​

  1. Start from disputed amount/time/account.
  2. Pull candidate ratings in the chosen time basis.
  3. Expand or fetch rated records to verify meter-level decomposition.
    • branch on rating_algorithm and cost_rating_algorithm, not on the amount alone;
    • for integer_rational_floor_v1, compare rate_identity, cost_rate_identity, exact rate pairs, and both snapshots;
    • for not_rated_missing_price_v1, expect nullable rate fields, zero amounts, and an explicit gate/missing-pricing-snapshot:v1 explanation.
  4. Pull allocations for those ratings and verify funding path: funding_kind, application_status, settlement_state, reversal_of_allocation_id.
  5. For ownership disputes, inspect attribution rows tied to the same rating_id.
  6. Use revenue report as aggregate confirmation only.

Allocation-state checks to always perform​

  • application_status: confirm whether amount was applied, clipped, reversed, quarantined, or failed.
  • settlement_state: confirm settlement progress (pending -> settling -> settled) or failure/void.
  • late_rating: identify ratings applied after the primary usage window.
  • reason_codes: preserve machine-readable reasons in incident notes.

What commonly breaks reasoning​

  • Mixing event time and rating time windows.
  • Assuming one rating always maps to one allocation.
  • Ignoring allocation reversals and reading only latest debit rows.
  • Treating aggregate report output as if it were the settlement ledger itself.
  • Treating unit_quantity_minor as a billing block rather than the divisor in an exact rational rate.
  • Comparing fingerprints without comparing the corresponding rate identity and snapshot discriminator.

Exact-rating fields​

For a priced record, revenue uses unit_price_xusd / unit_quantity_minor; cost uses unit_cost_xusd / cost_unit_quantity_minor. Both use integer_rational_floor_v1 and keep independent residual numerators. The pricing snapshot records previous_remainder_numer, amount_xusd, and next_remainder_numer, plus provenance for the selected catalog and contract inputs.

Missing pricing is not represented as an ordinary zero-priced rate. In Ops rated records it uses rating_algorithm=not_rated_missing_price_v1, nullable rate fields, and a missing-price snapshot. Consumers must therefore inspect the algorithm before reading rate-only fields. Gate commit responses expose the same distinction as a rating_status=priced|missing_price line union.

  • event ids (if source-fact dispute)
  • rating id + rated record ids
  • allocation ids and reversal links
  • funding kind + application/settlement statuses
  • exact time basis and query filters
  • request/window context (billing_account_id, from/to, sort basis)

Minimal trace checklist (copy into incident template)​

  1. billing_account_id, time basis, from/to, and sort configuration.
  2. Rating ids and their rated-record ids.
  3. Allocation ids with reversal links.
  4. Funding kind + application/settlement states.
  5. If ownership dispute: attribution ids and attribution kind/id pairs.

Verification checklist​

  • Quantity and amount decomposition in rated records explains the rating.
  • Allocation sums and statuses explain the applied/settled outcome.
  • Any reversal is explicitly tied to prior allocation/rating ids.
  • Ownership conclusions (if used) are backed by attribution rows, not by assumptions.

Next​