ADR-004: Settlement Jobs Must Fail Loudly On Non-Delivery
Status
Accepted
Date
2026-04-22
Context
Promotion settlement jobs in servers_v2 perform business-critical credits.
If a settlement batch reaches eligible players but downstream wallet credits fail,
reporting a green/success outcome is operationally unsafe.
Silent-success behavior causes:
- false scheduler health
- missing alerts
- delayed detection of broken credit flows
- misleading batch summaries
Decision
Settlement jobs must not report success when no eligible delivery was achieved.
Required semantics:
- if a batch has eligible targets and every attempted credit fails, the job must raise a failure
- full-batch failure is a release-blocking condition for that run
- logs and alerts must clearly distinguish:
- no eligible records
- partial success
- total delivery failure
Partial-failure rule:
- partial success must never be silently flattened into normal success
- partial outcomes must be explicitly logged and surfaced for follow-up
- if durable retry/compensation is not yet available, partial failure should be treated as degraded and visible to supervision
Consequences
Positive:
- broken downstream credit paths become visible immediately
- scheduler health better reflects business delivery
- operators can distinguish “nothing to do” from “everything failed”
Negative:
- more job runs may surface as failed until retry/compensation logic matures
- requires clearer settlement result reporting and alerting
Follow-Up
- apply the rule across rebate, cashback, and lossback settlement paths
- align scheduler health and runbooks with explicit degraded/failed settlement outcomes