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

# Medication Management & Reconciliation — Integration

> Feature ID: CL-05 Status: ✅ Implemented Spec Reference: CL-05-medication-management-reconciliation.md Last Updated: 2026-02-17 Last Verified: 2026-02-18

**Feature ID:** CL-05\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-05-medication-management-reconciliation.md](../../../specs/cl/specs/CL-05-medication-management-reconciliation.md)\
**Last Updated:** 2026-02-17\
**Last Verified:** 2026-02-18

***

## Table of Contents

* [Overview](#overview)
* [Quick Reference](#quick-reference)
* [Decision Trees](#decision-trees)
* [Pattern Library](#pattern-library)
* [Integration Points (from Spec)](#integration-points-from-spec)
* [API / Data Contracts](#api--data-contracts)
* [Labeled Code Examples](#labeled-code-examples)
* [Event Contracts](#event-contracts)
* [Security and RLS](#security-and-rls)
* [Common Mistakes](#common-mistakes)
* [Pre-Flight Checklist](#pre-flight-checklist)
* [Related Docs](#related-docs)

***

## Overview

CL-05 provides medication list management, medication reconciliation at transitions of care, and safety alerts (drug-drug, drug-allergy, duplicate therapy). It depends on CL-01 (patient chart); integrates with CL-06 (e-prescribing), CL-08 (clinical decision support), CL-09 (lab orders), and CL-12 (care transitions).

***

## Quick Reference

| Item                             | Value                                              |
| -------------------------------- | -------------------------------------------------- |
| Core tables                      | `cl_medications`, `cl_medication_reconciliations`  |
| Safety dependencies              | CL-08 (drug interactions), CL-09 (monitoring labs) |
| Transition triggers              | Admission, transfer, discharge, LOC change         |
| Controlled-substance requirement | Tamper-evident audit logging                       |

***

## Decision Trees

### Reconciliation trigger path

1. Detect transition event (admission/transfer/discharge/LOC change).
2. Create reconciliation record with `reconciliation_type`.
3. Compare prior list vs current orders and record discrepancies.
4. Resolve/acknowledge discrepancies and finalize reconciliation.

### Alert handling path

1. Submit active med list + allergies to CL-08 CDS service.
2. Receive interaction severity result.
3. If severity is critical/major, require clinician acknowledgement before save.

***

## Pattern Library

| Pattern                        | Usage                                                             |
| ------------------------------ | ----------------------------------------------------------------- |
| Event-triggered reconciliation | Transition events create reconciliation tasks                     |
| Platform CDS adapter           | CL-08 handles interaction logic while CL-05 owns medication state |
| Monitoring protocol automation | `monitoring_protocol` drives CL-09 lab workflow hooks             |

***

## Integration Points (from Spec)

| Dependency                              | Pattern     | Purpose                                                                                                                |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| CL-01 (Patient Chart)                   | Data        | Medication list displays on patient chart; `cl_medications.chart_id` → `cl_patient_charts.id`                          |
| CL-06 (E-prescribing)                   | API / Data  | E-prescribing creates medication records in `cl_medications`                                                           |
| CL-08 (Clinical decision support)       | API         | Interaction/monitoring alerts; drug interaction source: RxNav/NLM APIs (MVP); interface documented for future FDB swap |
| CL-09 (Lab orders)                      | API / Event | Lab orders triggered by monitoring protocols (`monitoring_protocol` JSONB)                                             |
| CL-12 (Care coordination / transitions) | Event / API | Reconciliation triggered at admission, transfer, discharge; `transition_event` can reference transition                |

***

## API / Data Contracts

* **Medication list:** `cl_medications` (organization\_id, chart\_id); status includes active, discontinued, on\_hold, completed, entered\_in\_error; soft-delete via `deleted_at`. RxNorm/NDC for interoperability.
* **Reconciliation:** `cl_medication_reconciliations`; `reconciliation_type` in ('admission', 'transfer', 'discharge', 'loc\_change'); `discrepancies` JSONB schema per spec Errata E-4; `transition_event` optional (event ID or free text for audit).
* **CL-08 drug interaction:** Request (medication list + allergy list); response (interactions with severity: critical, major, moderate, minor; duplicate therapy; allergy cross-reference). Data source: RxNav/NLM APIs (MVP); interface abstracted for future FDB (First Databank) swap.
* **CL-09 monitoring:** `cl_medications.monitoring_protocol` drives lab order triggers (lithium, clozapine, metabolic panel); schema per spec Errata E-2.

***

## Labeled Code Examples

### Example: medication reconciliation payload

```json theme={null}
{
  "organization_id": "org-uuid",
  "chart_id": "chart-uuid",
  "reconciliation_type": "discharge",
  "transition_event": "ADT-A03",
  "discrepancies": [
    { "medication": "Lithium", "issue": "dose_mismatch", "action": "review_required" }
  ]
}
```

### Example: monitoring protocol shape

```json theme={null}
{
  "labs": ["CMP", "A1C"],
  "frequency_days": 90,
  "alert_thresholds": { "lithium_level": "1.2" }
}
```

***

## Event Contracts

* **Inbound:** Care transition events (from CL-12 or workflow) trigger reconciliation workflow; payload should include chart\_id, transition type, and optional transition\_event reference.
* **Outbound:** `medication_reconciliation_completed` — published when a reconciliation record is finalized (status → 'completed'). Publisher: CL-05. Subscriber: PF-10 (notifications). Payload: `{ organization_id, chart_id, reconciliation_id, reconciliation_type, reconciled_by }`. Seeded in `fw_workflow_events` (category: operational). Registered in `KnownEventName` in `src/platform/events/types.ts`.

***

## Security and RLS

* RLS on `cl_medications` and `cl_medication_reconciliations` via `cl_has_org_access(organization_id, auth.uid())` (SECURITY DEFINER — matches CL-01 through CL-04 pattern). `FORCE ROW LEVEL SECURITY` enforced on both tables. No separate `cl_check_medication_access` function (removed — violated platform RLS pattern by querying RLS-protected tables and hardcoding roles).
* All UPDATE policies include WITH CHECK (constitution §5.2.4).
* Controlled substances (schedule II–V, is\_controlled): tamper-evident audit logging required (user\_id, timestamp, action, reason).
* Drug interaction and allergy data are PHI; audit logging required.

***

## Common Mistakes

| Mistake                                                         | Impact                      | Fix                                                               |
| --------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------- |
| Missing `request_trace_id` in eligibility-style external checks | Poor auditability           | Persist trace IDs for external calls                              |
| Not filtering soft-deleted rows                                 | Stale/incorrect med display | Always enforce `deleted_at IS NULL` in active views               |
| Skipping controlled-substance audit fields                      | Compliance exposure         | Require actor, timestamp, reason for controlled-substance updates |

***

## Pre-Flight Checklist

* [ ] Validate RLS helper usage on medication and reconciliation tables.
* [ ] Confirm reconciliation flow covers all transition types.
* [ ] Validate CDS integration fallback behavior for upstream outages.
* [ ] Confirm controlled-substance audit logging for creates/updates/discontinues.
* [ ] Validate monitoring protocol → lab order trigger mapping.

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [CL-PM-REFERRALS.md](./CL-PM-REFERRALS.md) (medication reconciliation at referral transitions)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)