Billing run: trigger, monitor, regenerate

A billing run reads the current state of eligibility, service-delivery, and the active rule configuration per payer, then runs the deterministic rules engine to produce per-member-per-month decisions. The output drives your billable roster CSV, your audit package, and (downstream) your invoice to the payer.

1. Triggering a run

From the Billing screen, click Trigger Billing Run. Provide:

• Billing month — default current month; prior months allowed for retroactive corrections.
• Payer(s) — one, several, or all active payers.
• Mode — Production (writes decisions, generates roster + audit package) or Simulation (engine runs, results surface, nothing persists).

2. Monitor

Each run shows live status (queued / running / completed / failed). The detail page has tabs:

• Summary — total members, billable members, total charge, mean charge, decision-class breakdown.
• Decisions — per-member list, filterable by class.
• Exceptions — raised during the run; resolve before the run is considered complete.
• Audit — the audit-chain segment for this run.

Typical duration: 5–15 minutes for tenants with 100,000+ members.

3. What the engine does

For each (payer × member × billing month) the rules engine:

1. Reads the member's current eligibility state and effective / termination dates.
2. Reads the payer's active rule configuration.
3. Applies the billable-day resolver, given state transitions and the retroactive window.
4. Applies file-precedence rules where multiple files asserted contradictory things.
5. Applies the retroactive window — reopens prior-month decisions if late evidence demands.
6. Applies the termination state machine for mid-cycle terminations.
7. If requiresServiceDelivery: true, reconciles against service-delivery events. Eligible members without a qualifying service become NOT_BILLED_NO_SERVICE.
8. Resolves combined benefits (primary code + suffix).
9. Picks the applicable pricing tier.
10. Writes the Decision row with all the inputs that drove it.

Layer 2 has a 100% test-coverage requirement enforced by CI.

4. Decision classes

Every decision belongs to a class:

• BILLED_ACTIVE — straightforwardly billable.
• BILLED_PARTIAL_TERM — billable for fewer than full month due to mid-cycle termination.
• BILLED_RETROACTIVE — newly billable due to late-arriving evidence.
• NOT_BILLED_RETROACTIVE — previously billed, now NOT, due to late evidence.
• NOT_BILLED_NO_SERVICE — eligible but no service-delivery event (Layer 2 reconciliation).
• NOT_BILLED_TERMINATED — terminated before the billing month.
• NOT_BILLED_PENDING — state did not resolve to billable.
• OVERRIDE_APPLIED — a mid-cycle rule override changed the outcome.

5. Completion + reconciliation

A run is Completed when:

• Every member has a decision (or an exception that surfaced a specific blocker).
• The audit chain for the run is closed (final hash computed and chained).
• Roster CSV + audit package are generated (production mode).

If exceptions remain unresolved at completion time, the run is marked Completed with exceptions; you can still export but the roster footer notes the unresolved count.

6. Regeneration

Re-run any prior cycle. Triggers:

• Corrected eligibility (a payer sent an amended file post-completion).
• Rule amendment that changes the calculation.
• Manual override that needs retroactive application.

Regeneration produces a new versioned run; the prior run is preserved.

7. Decision replay

The Decision Replay panel lets you re-run a single decision against an arbitrary rule version — "what would have billed if we'd been on rule v2.1 instead of v2.2?" Useful for payer disputes and internal investigations.

8. Exports

On completion (production mode): billable roster CSV is generated and downloadable; audit package PDF is queued for background generation. See Chapter 6 — Exports for details.

Permissions

• OWNER, ADMIN, BILLING_MANAGER can trigger and regenerate runs.
• OPERATIONS can view runs and decisions; cannot trigger.
• VIEWER is read-only.