> ## 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–PM: Episode of Care 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

PM-07 associates charges with individual encounters, but there is no platform-level “episode of care” grouping. For VBP contracts, utilization review, and FA cost analysis, organizations need to group encounters into episodes (e.g. “residential admission Jan 15 – Feb 28, 2026” or “IOP episode March 2026”). CL holds episode-relevant data (admission/discharge in CL-29, program enrollment in CL-27) but PM and FA cannot query by episode. This contract defines the `cl_episodes_of_care` data model and platform API `getEpisodeContext()` so PM and FA can attribute encounters and claims to episodes.

**Regulatory driver:** AHCCCS VBP episode-based payment models; SAMHSA episode analytics; HEDIS follow-up measures (FUH uses index hospitalization as episode anchor).

***

## Integration Type

* **Platform layer + data model:** CL owns episode definition and table; platform exposes read API for PM and FA.
* **No events required for basic use:** PM/FA call getEpisodeContext(patientId, date) or getEpisodesForChart(chartId) when needed. Optional: emit event when episode is closed for analytics.

***

## Data Model (CL-Owned)

### Table: `cl_episodes_of_care`

Episodes of care per chart (e.g. residential stay, IOP episode, outpatient episode).

* `id` UUID PRIMARY KEY
* `organization_id` UUID NOT NULL
* `site_id` UUID (optional)
* `chart_id` UUID NOT NULL REFERENCES cl\_patient\_charts(id) ON DELETE RESTRICT
* `episode_type` TEXT NOT NULL (e.g. 'residential', 'iop', 'php', 'outpatient')
* `episode_start` DATE NOT NULL
* `episode_end` DATE (null if ongoing)
* `primary_diagnosis` TEXT or ICD code (optional)
* `disposition` TEXT (optional)
* `program_id` or program name (optional; link to CL-27 program)
* `custom_fields` JSONB DEFAULT '{}'
* `created_at`, `updated_at`, `created_by`, `updated_by`
* **RLS:** Enable ROW LEVEL SECURITY on `cl_episodes_of_care`. Policies: (1) **organization\_isolation** — restrict rows to `auth.user_organization_id()` or equivalent so users see only their org’s episodes; (2) **chart\_access** — require that the related `cl_patient_charts` row exists and has the same `organization_id` (enforces chart-level access). All UPDATE policies MUST use WITH CHECK. Reference existing CL RLS patterns for `cl_patient_charts`.

**Indexes:** organization\_id, chart\_id, episode\_start, episode\_end.

***

## Platform Integration Layer

### API: getEpisodeContext

**Provider:** CL via Platform Integration Layer\
**Consumers:** PM, FA\
**Status:** 📝 Planned

#### Purpose

Given a patient/chart and date (or encounter), return the episode(s) that contain that date so PM can tag encounters with episode\_id and FA can attribute cost/claims to episodes.

#### Contract

* **Location:** `@/platform/clinical` or `@/platform/types` + platform function — see PLATFORM\_INTEGRATION\_LAYERS.md.
* **Single-episode lookup:** `getEpisodeContext(organizationId, chartId, date): Promise<EpisodeOfCare | null>` — returns the single episode that contains the given date for the chart, or null if none. Purpose: PM/FA need to tag an encounter with its episode.
* **Multi-episode query:** `getEpisodesForChart(organizationId, chartId, options?: { start?, end? }): Promise<EpisodeOfCare[]>` — returns all episodes for the chart, optionally filtered by date range. Purpose: list episodes for a patient or date range.
* **Return:** Episode id, episode\_type, episode\_start, episode\_end, primary\_diagnosis, disposition (no PHI beyond what caller already has access to for that chart).
* **Security:** Organization and chart scoped; caller must have access to chart; use SECURITY DEFINER RPC or platform layer that enforces RLS.

#### Usage (PM/FA)

* **PM:** When creating or displaying encounter, call getEpisodeContext(chartId, encounterDate) and store episode\_id on encounter (or in custom\_fields) for billing and reporting.
* **FA:** When aggregating cost or claims by episode, join to episode via encounter’s episode\_id or getEpisodeContext for date range.

***

## Implementation Notes

* **CL:** Create migration for `cl_episodes_of_care`; populate from CL-29 discharge/aftercare and CL-27 program enrollment where applicable; or allow manual episode creation. Expose getEpisodeContext via platform layer.
* **PM:** Add episode\_id (or equivalent) to encounter where possible; call platform API to resolve episode for encounter date.
* **FA:** Use episode\_id on encounters for episode-based reporting and VBP attribution.

***

## Testing Requirements

* [ ] cl\_episodes\_of\_care RLS: org and chart isolation
* [ ] getEpisodeContext(chartId, date) returns correct episode when date falls within episode range; null when no episode
* [ ] PM can attach episode\_id to encounter; FA can aggregate by episode

***

## References

* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)
* [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md)
* specs/cl/specs/CL-29-discharge-aftercare-planning.md
* specs/cl/specs/CL-27-behavioral-health-program-scheduling-templates.md
* specs/cl/CL-STRATEGIC-ROADMAP-20260302.md