Skip to main content

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.

Status: 📝 Planned
Created: 2026-03-02
Source: 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

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

ConsumerActionStatus
FAMap 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