Medication Management & Reconciliation — Integration

​

Table of Contents

• Overview
• Quick Reference
• Decision Trees
• Pattern Library
• Integration Points (from Spec)
• API / Data Contracts
• Labeled Code Examples
• Event Contracts
• Security and RLS
• Common Mistakes
• Pre-Flight Checklist
• Related Docs

​

Overview

​

Quick Reference

​

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

​

Integration Points (from Spec)

​

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

{
  "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

{
  "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

​

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
• CL-PM-REFERRALS.md (medication reconciliation at referral transitions)
• EVENT_CONTRACTS.md
• API_CONTRACTS.md

​

CL-05-EN-02 — med-list + reconciliation block adapters (CL-75, shipped 2026-07-02)