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

# Arizona CSPMP/PDMP Integration — Integration Contract

> Feature ID: CL-17 Status: \U0001F3D7️ Scaffolded (gateway integration pending vendor selection) -arizona-cspmp-pdmp-integration.md Last Updated: 2026-02-23…

**Feature ID:** CL-17\
**Status:** 🏗️ Scaffolded (gateway integration pending vendor selection)\
**Spec:** [CL-17-arizona-cspmp-pdmp-integration.md](../../../specs/cl/specs/CL-17-arizona-cspmp-pdmp-integration.md)\
**Last Updated:** 2026-02-23\
**Last Verified:** 2026-02-23

***

## Cross-Core Integration Matrix

| From Core  | To Core                         | Integration Pattern     | Status         | Documentation                                                                 |
| ---------- | ------------------------------- | ----------------------- | -------------- | ----------------------------------------------------------------------------- |
| CL (CL-17) | CL-06, CL-01, External gateways | API / query-in-workflow | 🏗️ Scaffolded | [CL-17 spec](../../../specs/cl/specs/CL-17-arizona-cspmp-pdmp-integration.md) |

***

## Overview

CL-17 defines Arizona Controlled Substances Prescription Monitoring Program (CSPMP) / PDMP integration: query-in-workflow for controlled substance prescribing, prescriber attestation, delegate access, and audit trail per A.R.S. § 36-2606. Integration with external gateways (PMP Gateway/NABP, Bamboo Health/Appriss, Arizona HIE) and with CL-06 (e-prescribing) and CL-01 (patient chart).

**Query-in-workflow (fail-closed):** Query-in-workflow MUST be fail-closed. Clinicians must NOT prescribe controlled substances when a required PDMP query fails or is unavailable unless an exception is recorded. Enforce at the application layer and in workflows that use `cl_pdmp_queries`; see Security and RLS below.

***

## Integration Points

| Dependency                        | Pattern          | Purpose                                                                          |
| --------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| CL-06 (E-Prescribing)             | Direct           | PDMP query embedded in e-prescribing workflow for controlled substances          |
| CL-01 (Patient Chart)             | Direct           | PDMP query history on patient chart                                              |
| CL-08 (Clinical Decision Support) | Planned (future) | PDMP results (high-risk indicators) may trigger CDS alerts in e-prescribing flow |
| PMP Gateway (NABP)                | External         | PDMP query API                                                                   |
| Bamboo Health / Appriss           | External         | PDMP query API                                                                   |
| Arizona HIE                       | External         | PDMP query API                                                                   |

***

## API / Data Contracts

### External gateway (PMP Gateway / Bamboo Health / Arizona HIE)

* **Authentication:** Credentials MUST be loaded from the platform vault only via `credentials_vault_ref`; no API keys or tokens in code or config. Use the existing platform vault pattern.
* **Request/response:** Request/response schemas for PDMP gateway calls to be defined when implementation is chosen (e.g. patient identifiers, date range, prescriber/delegate context). Document in this section when available.
* **Resilience (API alignment):** Use a **per-attempt timeout** of 5s (aligned to NFR-1). **Retry policy:** 2 retries with exponential backoff (initial delay 200ms, multiplier 2, max backoff 1s). **Maximum total timeout:** 15s; after that the integration MUST **fail-closed** (do not allow prescribing without recording the failure). Any fail-closed event or gateway unavailability MUST be recorded in `cl_pdmp_queries` with `results_summary.exception_type` set to `pdmp_unavailable`. Include diagnostic fields in `results_summary` for debugging (e.g. `attempt_count`, `last_error`).
* **Rate limiting:** If the gateway documents rate limits, implement client-side throttling per org/facility and document limits in this section when known.

### `cl_pdmp_queries`

* **Scope:** `organization_id` + `chart_id`; PHI — full RLS.
* **Key columns:** `chart_id`, `queried_by`, `queried_on_behalf_of`, `prescriber_attestation`, `results_reviewed_at`, `prescription_id`, `gateway_transaction_id`, `gateway_provider`, `interstate_query`, `states_queried`.

### `cl_pdmp_configuration`

* **Scope:** `organization_id`; org-level gateway and feature toggles.
* **Key columns:** `gateway_provider` (CHECK: `pmp_gateway` | `bamboo_health` | `arizona_hie`), `auto_query_enabled`, `interstate_query_enabled`, `delegate_access_enabled`, `credentials_vault_ref`.

***

## Event Contracts

### `cl_pdmp_query_completed` (Planned — Deferred)

**Status:** Planned but deferred from initial implementation.\
**Rationale:** CL-17 uses synchronous query-in-workflow. The `cl_pdmp_queries` table INSERT is the primary audit trail per A.R.S. § 36-2606. A domain event is not required for the core compliance use case. The event will be implemented if downstream consumers need to react to PDMP queries (e.g., CL-08 CDS high-risk alerts, GR compliance automation).

**When to implement:** When CL-08 or GR needs to subscribe to PDMP query completion for automated processing.

**Registered in:** `src/platform/events/types.ts` as `KnownEventName` (`cl_pdmp_query_completed`); `EVENT_CONTRACTS.md` planned events table.

**Subscriber controls (required before release):**

* Channel subscribers must be explicitly allowlisted and limited to approved consumers (e.g., CL-08 CDS and designated governance automations).
* Consumers must verify active 42 CFR Part 2 consent for the referenced chart before processing protected fields.
* Consumer access to this event payload must be audit-logged with the same rigor as direct `cl_pdmp_queries` access.

**Stub payload (to be finalized when implemented):**

```typescript theme={null}
interface PdmpQueryCompletedPayload {
  query_id: string;           // UUID of cl_pdmp_queries record
  organization_id: string;
  chart_id: string;           // 42 CFR Part 2 protected
  queried_by: string;         // user UUID
  gateway_provider: string;   // 'pmp_gateway' | 'bamboo_health' | 'arizona_hie'
  patient_match_found: boolean; // 42 CFR Part 2 protected
  interstate_query: boolean;
  states_queried: string[];
  // Pre-computed, non-identifying summary fields for downstream CDS without secondary PHI query:
  risk_level: 'none' | 'low' | 'moderate' | 'high' | 'critical';
  high_risk_indicators: string[]; // e.g. ['multiple_prescribers', 'high_opioid_dose']
  summary_text?: string;
  evaluation_time: string;    // ISO timestamp
}
```

***

## Security and RLS

* **Permission keys (PF-30):** `cl.pdmp.queries.view`, `cl.pdmp.queries.create`, `cl.pdmp.configuration.manage` (see spec for usage).
* RLS enabled on `cl_pdmp_queries` and `cl_pdmp_configuration` with organization isolation.
* Policies: org isolation, prescriber access, delegate access, admin access.
* All policies MUST use SECURITY DEFINER helpers (no direct queries to RLS-protected tables); UPDATE policies MUST include WITH CHECK (constitution §5.2.4).
* **Audit (minimalism):** Application logs MUST use only non-PII/PHI identifiers: query `id`, `organization_id`, timestamp, and optionally `gateway_transaction_id` for correlation. Do NOT log patient or prescriber identifiers. Retain audit records per HIPAA (e.g. 6-year retention) where applicable. INSERT and updates to `prescriber_attestation` / `results_reviewed_at` form the A.R.S. § 36-2606 evidence trail.

***

## Related Docs

* [CL-06 E-Prescribing Integration](e-prescribing-epcs-integration.md)
* [CL-01 Patient Chart Integration](patient-chart-clinical-summary-integration.md)
* Spec: [CL-17-arizona-cspmp-pdmp-integration.md](../../../specs/cl/specs/CL-17-arizona-cspmp-pdmp-integration.md)