Payer-scoped modifier overrides

Outcome

Modifier injection rules and modifier_validation rule sets are scoped to specific payers when they should be, with deterministic precedence.

Prerequisites

• config.update for rcm_reference.modifier_injection_rule writes.
• rules.update for YAML rule-set authoring.

Two layers of payer-scoped precedence

Layer	Source	Precedence
rcm_reference.modifier_injection_rule	Master ref data	payer_id(4) > state_code(2) > service_line(1). Partial unique index ux_mir_active_scope (master 044) guarantees no two active rows share a scope, so the winner is fully deterministic.
YAML rule sets (PRE_SUBMIT_VALIDATE / COMPANION_GUIDE_VALIDATE)	config.rule_set_version + config.rule_scope	ResolutionService.calculateScopeMatchScore weights scope.payerId at 10000, so a rule-set version scoped to a specific payer outranks every state-only or tenant-only alternative.

Diagnose why a modifier was (or wasn't) auto-injected

When a claim carries (or is missing) an unexpected modifier and you have the (procedure_code, state_code, payer_id, service_line) facets:

SELECT
  rule_id, state_code, payer_id, service_line,
  trigger_type, trigger_value, modifier_code, description
FROM rcm_reference.modifier_injection_rule
WHERE is_active = true
  AND procedure_code = :procedure_code
  AND (state_code   IS NULL OR state_code   = :state_code)
  AND (payer_id     IS NULL OR payer_id     = :payer_id)
  AND (service_line IS NULL OR service_line = :service_line)
ORDER BY
  (payer_id     IS NOT NULL) DESC,
  (state_code   IS NOT NULL) DESC,
  (service_line IS NOT NULL) DESC,
  effective_from DESC;

The top row is what ModifierInjector would pick. Rows below are fall-throughs that only matter when the top row is removed or expired.

Author a new payer-scoped override

Prefer a payer-scoped row with state_code = NULL when the override applies across every state — this is the shape used by master 045 for Anthem / UHC / Aetna / Cigna. State-qualified payer overrides (state_code = 'OH' + payer_id = …) are only needed when a payer publishes different rules per state.

Idempotency: always existence-check on (procedure_code, state_code, payer_id, service_line, trigger_type, trigger_value) before insert. The partial unique index ux_mir_active_scope enforces the same invariant, but checking avoids a hard error during a bulk re-run.

Author a new payer-scoped YAML rule set

PRE_SUBMIT_VALIDATE and COMPANION_GUIDE_VALIDATE rule sets scope on payer_id in config.rule_scope.

1. Create a rule-set version + artifact with kind=modifier_validation and the payer's prohibition (e.g., prohibit: [FQ]) in the artifact body. Use the Rules engine editor.

2. Insert a config.rule_scope row with rule_set_version_id set to the new version and payer_id = <UHC payer_id>.

3. Publish the version. Future claims whose scrubContext.payerId equals the UHC id resolve this rule set ahead of any state-only or tenant-only rule sets on the same (procedure_code, state).

Validation

Check	Expected
ux_mir_active_scope index intact	No conflicting active rows
ResolutionService for a UHC charge	Resolves to the UHC-scoped rule set
Diagnostic query	Shows the winning rule on top

Troubleshooting

Symptom	Cause	Fix
Modifier auto-injection unexpected	A new payer-scoped row outranked the previous winner	Use the diagnostic query; re-evaluate scope.
prohibit rule not firing for UHC	config.rule_scope.payer_id not set	Add the scope row.
Bulk seed fails with index violation	Pre-existing active row at same scope	Run existence-check first.

Cross-references

• Publish rule changes for the rule editor.
• Modifier rules editing & simulation for the UI surface.

Next

4.4 — Commercial payer onboarding