> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Vendor Clearinghouse Failover — Compliance Evidence

> Version: 1.0.0 Last Updated: 2026-05-15 Spec: PM-15-P2-EN-01 Plan: PM-15-P2-EN-01-PLAN Tasks: PM-15-P2-EN-01-TASKS Context: PM-15-P2-EN-01-CONTEXT Implementati…

**Version:** 1.0.0
**Last Updated:** 2026-05-15
**Spec:** [PM-15-P2-EN-01](../../../specs/pm/specs/PM-15-P2-EN-01-clearinghouse-multi-vendor-failover.md)
**Plan:** [PM-15-P2-EN-01-PLAN](../../../specs/pm/plans/PM-15-P2-EN-01-clearinghouse-multi-vendor-failover-PLAN.md)
**Tasks:** [PM-15-P2-EN-01-TASKS](../../../specs/pm/tasks/PM-15-P2-EN-01-TASKS.md)
**Context:** [PM-15-P2-EN-01-CONTEXT](../../../specs/pm/specs/PM-15-P2-EN-01-CONTEXT.md)
**Implementation Log:** [specs/pm/IMPLEMENTATION\_LOG.md](../../../specs/pm/IMPLEMENTATION_LOG.md) → PM-15-P2-EN-01 entry
**Sign-Off:** [PM-15-P2-EN-01-COMPLIANCE-SIGNOFF.md](../../../specs/pm/reviews/PM-15-P2-EN-01-COMPLIANCE-SIGNOFF.md)
**Regulations:**

* 45 CFR 162 — X12 5010 transaction continuity
* 45 CFR 164.308(b)(1), 164.502(e) — Business Associate Agreement (BAA) controls
* 45 CFR 164.312(a)(2)(iv) — Credential encryption at rest
* 45 CFR 164.312(b) — Audit controls
* 45 CFR 164.312(e)(2)(ii) — PHI encryption in transit

***

## 1. Scope

PM-15-P2-EN-01 extends the PM-15-P2 single-vendor (Waystar) baseline with:

* Secondary clearinghouse adapters (Availity, Change Healthcare) gated behind a recorded BAA approval per organization.
* Per-payer route overrides (`pm_payer_clearinghouse_routes`).
* Health-aware failover with a configurable degradation threshold (`pm_clearinghouse_config.failover_*`).
* Audited failover transitions (config changes + runtime route flips) written to `pm_audit_log`.

The PM-15-P2 X12 5010 transaction inventory (837P, 835, 270/271, 999, 277CA) is unchanged and remains the canonical evidence for transport conformance.

## 2. Vendor Adapter Inventory

| Vendor            | Adapter                                | Source                                                             | Status                  |
| ----------------- | -------------------------------------- | ------------------------------------------------------------------ | ----------------------- |
| Waystar           | `WaystarClearinghouseAdapter`          | `src/cores/pm/services/clearinghouse/waystar-adapter.ts`           | ✅ Production (PM-15-P2) |
| Availity          | `AvailityClearinghouseAdapter`         | `src/cores/pm/services/clearinghouse/availity-adapter.ts`          | 🟡 Stub — gated by BAA  |
| Change Healthcare | `ChangeHealthcareClearinghouseAdapter` | `src/cores/pm/services/clearinghouse/change-healthcare-adapter.ts` | 🟡 Stub — gated by BAA  |

Stubs MUST NOT carry PHI until the secondary's BAA gate (§4) is satisfied **and** transport hardening is signed off.

## 3. Routing Precedence (Continuity — 45 CFR 162)

Implemented by `resolveVendorRoute()` (`src/cores/pm/services/clearinghouse/router.ts`). Pure, deterministic, unit-tested.

1. Per-payer override (`pm_payer_clearinghouse_routes.preferred_vendor`).
2. Configured primary vendor (`pm_clearinghouse_config.clearinghouse_provider`).
3. Configured secondary vendor — only when failover is enabled, secondary is configured, and the primary has been continuously unhealthy for ≥ `failover_threshold_minutes`.

In-flight transactions are never re-routed; the router is consulted at submission time only.

**Tests:** `src/cores/pm/services/clearinghouse/router.test.ts` (6 cases — payer override, disabled failover, no secondary, healthy primary, threshold-not-met, threshold-met failover).

## 4. BAA Gate (45 CFR 164.308(b)(1), 164.502(e))

* The Failover Settings UI (`src/cores/pm/components/clearinghouse/FailoverSettingsCard.tsx`) reads `pm_clearinghouse_config.custom_fields.baa_approved_vendors: string[]`.
* The **Save** action and the failover-enabled toggle are blocked when the chosen secondary vendor is not present in the approved list.
* User-visible copy when blocked: *"This vendor cannot be enabled until compliance approval is recorded."* (per `PM-15-P2-EN-01-CONTEXT.md` §Example Phrasing).
* Storage location is interim — a dedicated `pm_clearinghouse_baa_approvals` table is tracked as a follow-up in `specs/pm/IMPLEMENTATION_LOG.md`.

## 5. Audit Controls (45 CFR 164.312(b))

Two complementary audit paths, both PHI-free:

| Trigger                                               | Action                                                                                                                               | Source                                                                            |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| Admin saves failover settings                         | `pm_audit_log.action = 'failover_config_change'` with prior/new `secondary_vendor`, `failover_enabled`, `failover_threshold_minutes` | `useUpdateFailoverConfig()` in `src/cores/pm/hooks/useClearinghouseFailover.ts`   |
| Runtime router flips vendor for an (org, payer) scope | `pm_audit_log.action = 'clearinghouse_route_failover'` with prior vendor, new vendor, routing reason, payer scope, actor             | `resolveVendorRouteWithAudit()` in `src/cores/pm/services/clearinghouse/audit.ts` |

Runtime emission is deduplicated by an in-memory (org, payer) cache so steady-state routing does not spam the audit log; only transitions are written. Failures are sent to Sentry and never block transaction submission.

**Tests:** `src/cores/pm/services/clearinghouse/audit.test.ts` (4 cases — first decision, dedupe on no-op, transition row, payer scoping).

## 6. Credential & Transport Security (45 CFR 164.312(a)(2)(iv), 164.312(e)(2)(ii))

Inherits all PM-15-P2 controls. No additional credential surface is introduced by EN-01:

* Vendor credentials remain in Edge Function Secrets (`Deno.env.get`); no credentials in DB, logs, or app state.
* All vendor traffic is HTTPS (TLS 1.2+); REST-only transport (SFTP deferred).
* Failover settings store only vendor codes, booleans, and integer thresholds — no credentials, no PHI.

## 7. Tenant Isolation (Constitution §5.1)

* `pm_clearinghouse_config`, `pm_payer_clearinghouse_routes`, and `pm_audit_log` are all `organization_id`-scoped with `FORCE ROW LEVEL SECURITY`.
* All hooks scope reads/writes by `useOrganization()` and filter mutations on `organization_id`.
* RLS test: `tests/rls/pm/pm-clearinghouse-failover.test.ts`.

## 8. Test Inventory

| Layer                  | Path                                                 |
| ---------------------- | ---------------------------------------------------- |
| Router unit            | `src/cores/pm/services/clearinghouse/router.test.ts` |
| Runtime audit unit     | `src/cores/pm/services/clearinghouse/audit.test.ts`  |
| RLS / tenant isolation | `tests/rls/pm/pm-clearinghouse-failover.test.ts`     |

## 9. Seed Test Data

Synthetic, PHI-free fixtures scoped to NorthSight Recovery: `supabase/seeds/pm/pm-15-p2-en-01-test-data.sql`
(`Test-PM-15-P2-EN-01-Normal`, `-Edge`, `-Empty`). Apply via Supabase Studio SQL editor against the dev project.

## 10. Open Follow-Ups

Tracked in `specs/pm/IMPLEMENTATION_LOG.md` → PM-15-P2-EN-01:

* Mobile Sheet variant for `PayerRoutesTable` add/edit flows.
* Replace ad-hoc empty-state copy with shared `<EmptyState />`.
* Edge-function (server-side) clearinghouse transport for the secondary adapters.
* Dedicated `pm_clearinghouse_baa_approvals` table to replace the JSONB interim store.
* Server-side router-driven audit emission once submission moves to edge functions (current emission is client-side only).

***

## Sign-Off Status

See [PM-15-P2-EN-01-COMPLIANCE-SIGNOFF.md](../../../specs/pm/reviews/PM-15-P2-EN-01-COMPLIANCE-SIGNOFF.md) for the compliance officer checklist.