> ## 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.

# CL–FA: VBP Quality Data Pipeline Integration

> Status: 📝 Planned Created: 2026-03-02 Source: specs/cl/CL-STRATEGIC-ROADMAP-20260302.md Constitution Reference: Section 1.3 (Integration Patterns); no direct…

**Status:** 📝 Planned\
**Created:** 2026-03-02\
**Source:** [specs/cl/CL-STRATEGIC-ROADMAP-20260302.md](../../../specs/cl/CL-STRATEGIC-ROADMAP-20260302.md)\
**Constitution Reference:** Section 1.3 (Integration Patterns); no direct core-to-core imports.

***

## Purpose

AHCCCS VBP (value-based purchasing) contracts tie at-risk payment to clinical quality metrics (e.g. HEDIS, AHCCCS-specific measures). FA needs to receive quality measure results from CL to calculate incentive payments earned, at-risk amounts, and quality-adjusted revenue. This contract defines the event and optional platform API so FA can consume quality measure period results from CL-15/CL-35 without direct CL table access.

**Regulatory driver:** AHCCCS managed care contracts; CMS MA STARS financial incentives; SAMHSA CCBHC PPS rate calculations.

***

## Integration Type

* **Event-based:** CL publishes when a quality measure period is calculated (e.g. end of reporting period).
* **Platform layer (optional):** FA may also call `getQualityMeasureResults(orgId, measurePeriod)` for on-demand or reconciliation.

***

## Event Contract

### Event: `cl_quality_measure_period_calculated`

**Event:** `cl_quality_measure_period_calculated`\
**Channel:** `cl_events` (canonical; CL is the publisher — use this channel for all CL quality measure events)\
**Publisher:** CL (CL-15 Clinical Reporting & Quality Measures / CL-35 Population Health)\
**Subscribers:** FA (VBP payment adjustment, quality-adjusted revenue)\
**Status:** 📝 Planned

#### Purpose

Notify FA that a quality measure period has been calculated so FA can map measure performance to VBP contract payment adjustments and update financial reporting.

#### Trigger Conditions

* **Trigger 1:** Completion of measure period calculation in CL-15 or CL-35 (e.g. HEDIS AMM, FUH, FUM, IET; or custom org measures).
* **Trigger 2:** May be emitted by batch job or on-demand when “finalize measure period” is run.

#### Payload Schema

```typescript theme={null}
interface ClQualityMeasurePeriodCalculatedPayload {
  event_type: 'cl_quality_measure_period_calculated';
  organization_id: uuid;
  timestamp: timestamptz;
  site_id?: uuid;
  correlation_id?: uuid;
  measure_id: string;           // e.g. 'HEDIS_AMM', 'HEDIS_FUH', 'HEDIS_FUM', 'HEDIS_IET'
  period_start: string;         // ISO date
  period_end: string;           // ISO date
  denominator_count: number;
  numerator_count: number;
  rate?: number;                // optional calculated rate
  /** NO PHI — aggregates only. Allowed keys: source_system, processing_timestamp, aggregate metrics/counts. Do NOT include patient-level data. */
  metadata?: Record<string, unknown>;
}
```

**Note:** The `metadata` property must not contain PHI or patient-level data. Allowed shape: aggregate metrics, counts, `source_system`, `processing_timestamp`. Producers should use a canonical metadata schema or runtime validator; see platform event validation for the constraint.

#### Metadata Validation Requirement

Event publishers (CL-15 and CL-35) **must** validate the `metadata` field at runtime before publishing:

* **Canonical schema:** Define a strict `MetadataSchema` (e.g. Zod or JSON Schema) with allowed keys only: `source_system` (string), `processing_timestamp` (ISO string), and optional aggregate metric keys (e.g. counts). No arbitrary or unknown keys permitted.
* **Validation point:** In the function that constructs and sends `ClQualityMeasurePeriodCalculatedPayload` (e.g. the publish/prepare path that builds the payload and calls the event bus), run `metadata` through the validator immediately before publish. If validation fails (unknown keys, invalid types, or PHI-like values), **reject** the payload and throw or return a clear error (e.g. "Metadata validation failed: disallowed key 'patient\_count'").
* **Rejection semantics:** Any payload with non-allowed keys or invalid types must not be published; the caller receives a structured error so the bug can be fixed at the source. Sanitization of unknown keys is not sufficient — reject the entire payload to prevent PHI leakage via metadata.

#### Consumer Actions

| Consumer | Action                                                                                                       | Status     |
| -------- | ------------------------------------------------------------------------------------------------------------ | ---------- |
| FA       | Map measure\_id and rate to VBP contract terms; update incentive/at-risk calculations; persist for reporting | 📝 Planned |

#### Operational Requirements

* **Idempotency:** FA may key by (organization\_id, measure\_id, period\_start, period\_end); overwrite or ignore duplicate.
* **Retry:** Consumer may retry; idempotent processing.
* **Versioning:** Payload version field if schema evolves.

***

## Platform Layer (Optional)

### API: getQualityMeasureResults

**Provider:** CL via Platform Integration Layer\
**Consumer:** FA\
**Status:** 📝 Planned

* **Purpose:** Allow FA to fetch quality measure results for a given org and period (e.g. for reconciliation or on-demand report).
* **Contract:** `getQualityMeasureResults(organizationId, periodStart, periodEnd): Promise<QualityMeasureResult[]>`.
* **Return type `QualityMeasureResult`:** `{ measure_id: string; period_start: string; period_end: string; denominator_count: number; numerator_count: number; rate?: number }`. No PHI; aggregates only.
* **Semantics:** Returns an empty array `[]` when no results exist for the period. Returns 403 (or throws an authorization error) when the caller does not have valid org access.
* **Performance:** Recommend caching for frequently-requested periods; rate-limit synchronous per-transaction calls to avoid overload. Prefer event-driven consumption where possible.
* **Security:** Organization-scoped; FA caller must have org access; no PHI in result (aggregates only).

***

## Implementation Notes

* **CL-15/CL-35:** When measure period is finalized, publish `cl_quality_measure_period_calculated` (client or edge function). Optionally persist in `cl_quality_measure_periods` or equivalent.
* **FA:** Subscribe to event; parse payload; map to VBP contract; update financial records. Optionally call getQualityMeasureResults for full list.

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event emitted when CL finalizes measure period
* [ ] FA subscriber receives event and updates VBP-related data (or logs); no PHI in payload
* [ ] getQualityMeasureResults (if implemented) returns org-scoped aggregates only

***

## References

* [CL-15-clinical-reporting-quality-measures-INTEGRATION.md](clinical-reporting-quality-measures-integration.md)
* [EVENT\_CONTRACTS.md](EVENT_CONTRACTS.md) — add `cl_quality_measure_period_calculated`
* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)
* specs/cl/specs/CL-35-population-health-care-gap-management.md
* specs/cl/CL-STRATEGIC-ROADMAP-20260302.md