> ## 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–RH: Residential Medication Administration Record (MAR) 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

Patients in recovery housing (RH) who are on prescribed medications (e.g. MOUD: buprenorphine, methadone, naltrexone) need medication administration documented in the residential context. Recovery housing staff who witness or assist self-administration need a Medication Administration Record (MAR) that is connected to the clinical medication list (CL-05) but accessible to non-clinical residential staff. This contract defines the event and platform layer so RH can consume active medication data from CL without direct CL→RH imports.

**Regulatory driver:** AZDHS sober living home licensing (AAC Title 9 Ch 12) for medication management in licensed facilities; NARR Level III/IV standards for supervised medication; 42 CFR Part 8 for MOUD in residential; **42 CFR Part 2 (Confidentiality of Substance Use Disorder Patient Records)** — imposes stricter confidentiality requirements that must inform security, multi-tenancy, and RLS implementations for any SUD-related medication data.

***

## Integration Type

* **Event-based:** CL publishes when medication list changes; RH subscribes to refresh MAR.
* **Platform layer:** Read API for RH to fetch resident medications (e.g. `getResidentMedications()`) so RH can display MAR without querying CL tables directly.

***

## Event Contract

### Event: `cl_medication_list_updated`

**Event:** `cl_medication_list_updated`\
**Channel:** Use `cl_events` for all CL medication list publications. Use `cl_pm_events` only when the event is tied to a specific PM encounter context (e.g. medication reconciliation at encounter); otherwise publish to `cl_events` and let RH filter by chart\_id.\
**Publisher:** CL (CL-05 Medication Management)\
**Subscribers:** RH (recovery housing MAR refresh)\
**Status:** 📝 Planned

#### Purpose

Notify downstream systems (e.g. RH) when a patient's active medication list has changed so that residential MAR can be updated without polling.

#### Trigger Conditions

* **Trigger 1:** INSERT or UPDATE on CL medication list table (e.g. `cl_medications` or equivalent) that affects “active” medications for a patient who has a current residence in RH (or broadcast; RH filters by resident).
* **Trigger 2:** Optional: on encounter or reconciliation completion that updates active meds.

#### Payload Schema

```typescript theme={null}
interface ClMedicationListUpdatedPayload {
  event_type: 'cl_medication_list_updated';
  organization_id: uuid;
  timestamp: timestamptz;
  chart_id: uuid;
  site_id?: uuid;
  user_id?: uuid;
  correlation_id?: uuid;
  // Optional: list of medication ids or summary so RH can refetch
  medication_ids?: uuid[];
}
```

#### Consumer Actions

| Consumer | Action                                                                                                                         | Status     |
| -------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| RH       | Refresh MAR for affected resident(s); call platform layer `getResidentMedications(chart_id)` or equivalent to get current list | 📝 Planned |

#### Operational Requirements

* **Idempotency:** RH can refetch full list by chart\_id; duplicate events result in same MAR state.
* **Retry:** Event consumer may retry; idempotent refetch is safe.
* **Versioning:** Add `event_version: '1.0'` if payload evolves.

#### Security and Compliance (event `cl_medication_list_updated`, payload `ClMedicationListUpdatedPayload`, `chart_id`)

* **42 CFR Part 2:** Require explicit patient consent or documented integrated-care consent before RH may subscribe to or receive medication data for SUD-related medications. Enforce subscriber authorization checks scoped to `chart_id` prior to publishing. Log all publications and recipients for audit. Apply multi-tenancy/RLS controls where applicable. Publisher-side filtering: only emit events for residents for whom RH is authorized to receive medication data.

***

## Platform Integration Layer

### API: getResidentMedications (or equivalent)

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

#### Purpose

RH needs a read-only way to get the active medication list for a resident (by chart\_id or resident\_id that maps to chart) for MAR display. No PHI beyond what RH is already authorized to access for that resident.

#### Contract

* **Location:** `@/platform/clinical` — medication-related APIs remain colocated with clinical data; no separate `@/platform/residential-mar` layer. See [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md).
* **Function/hook:** e.g. `getResidentMedications(organizationId, chartId): Promise<ResidentMedicationSummary[]>` returning medication name, dose, route, frequency, prescriber, start/end date, and any MAR-relevant flags (e.g. self-admin vs witnessed).
* **Security:** Organization and chart scoped; caller must have access to the resident’s chart (via RH resident–chart link). Use SECURITY DEFINER or RPC that enforces org/chart access. **42 CFR Part 2 (MOUD):** Callers must present and verify documented consent or a qualifying exception before MOUD-related fields are returned; SECURITY DEFINER/RPC must filter or redact MOUD entries when authorization is missing. Store/validate consent at chart level (e.g. CL-11). Audit log every access to 42 CFR Part 2–protected medication records (who, when, chart\_id).

#### Data Flow

1. CL-05 maintains active medication list per chart.
2. When med list changes, CL publishes `cl_medication_list_updated` (optional).
3. RH (or platform layer) subscribes and/or calls `getResidentMedications(chart_id)` to refresh MAR.
4. RH displays MAR to residential staff; no direct CL table access from RH code.

***

## Implementation Notes

* **CL side:** Emit event on medication list change; expose read-only API or RPC that returns active medications for a chart (with org\_id check).
* **RH side:** Map resident to chart\_id (existing or new); on event or on MAR view load, call platform API to get medications; render MAR view. Platform layer lives in `@/platform/clinical`; see PLATFORM\_INTEGRATION\_LAYERS.md.

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event fires when CL medication list updated for a chart
* [ ] RH (or test consumer) receives event and refetches; MAR data matches CL list
* [ ] getResidentMedications returns only org/chart-authorized data; RLS or RPC enforces tenant isolation
* [ ] **42 CFR Part 2 — getResidentMedications redaction:** Verify `getResidentMedications` redacts MOUD/Part 2 entries when consent is missing (no MOUD medication details in response for that chart when CL-11 consent not present or revoked).
* [ ] **42 CFR Part 2 — medication-change event gating:** Verify the integration does not publish the medication-change event (or equivalent) when the subscriber lacks Part 2 authorization for the chart; test with unauthorized RH context.
* [ ] **42 CFR Part 2 — audit logging:** Validate audit logging captures all medication access attempts, including denied reads (failed consent check or unauthorized caller); reference PF-40 and CL-11 audit requirements.
* [ ] **42 CFR Part 2 — consent revocation:** Confirm consent revocation prevents subsequent access and events; after revocation, `getResidentMedications` must not return Part 2–protected meds and no new events for that chart to that consumer.

***

## References

* [CL-05-medication-management-INTEGRATION.md](medication-management-integration.md)
* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)
* [EVENT\_CONTRACTS.md](EVENT_CONTRACTS.md) — add `cl_medication_list_updated` entry
* [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md)
* specs/cl/CL-STRATEGIC-ROADMAP-20260302.md