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

# Integration Documentation: PM-55 — ONC HTI-1 / USCDI v3 Patient Access API

> PM-55 implements the ONC HTI-1 (45 CFR 170.315(b)(11) and (g)(10)) Patient Access API, exposing USCDI v3 / US Core 7.0 FHIR R4 resources via SMART App Launch w…

**Spec:** PM-55
**Created:** 2026-05-06
**Status:** 📝 Planned (WS1 — schema + permissions)

***

## Overview

PM-55 implements the ONC HTI-1 (45 CFR 170.315(b)(11) and (g)(10)) Patient Access API,
exposing USCDI v3 / US Core 7.0 FHIR R4 resources via SMART App Launch with OAuth2.
It also delivers the 21st Century Cures Act §4004 information-blocking review workflow
for Compliance Officers. PM-55 is the canonical PM owner of FHIR access logging,
app-authorization consent, and information-blocking dispositions.

***

## Integration Points

### Platform Foundation Dependencies

| PF Feature                    | Integration Type           | Usage                                                                |
| ----------------------------- | -------------------------- | -------------------------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct                     | Tenant isolation on every FHIR resource read                         |
| PF-02 (RBAC)                  | Direct                     | `pm.fhir.app.manage`, `pm.fhir.consent.*`, `pm.compliance.*` keys    |
| PF-04 (Audit & Event Stream)  | Direct                     | `pm.fhir_access_logged` per FHIR request; immutable audit            |
| PF-10 (Notifications)         | Platform Integration Layer | Compliance review queue assignment notifications                     |
| PF-96 (Jurisdiction Profiles) | Platform Integration Layer | State info-blocking carve-outs (e.g., NY mental health, MA HIV)      |
| PF-12 (Patient Portal Shell)  | UI host                    | `AuthorizedAppsPage`, `AppConsentSheet` rendered inside portal shell |

### Same-Core Dependencies

| PM Feature                   | Integration Type | Usage                                                                   |
| ---------------------------- | ---------------- | ----------------------------------------------------------------------- |
| PM-01 (Patient Demographics) | Direct read      | Source for `Patient` FHIR resource (uses `pm_patients.id` as bare UUID) |
| PM-02 (Insurance)            | Direct read      | Source for `Coverage` FHIR resource                                     |
| PM-03 (Scheduling)           | Direct read      | Source for `Appointment` FHIR resource via `pm_appointments`            |
| PM-08 (Claims)               | Direct read      | Source for `ExplanationOfBenefit` FHIR resource                         |

### Cross-Core Dependencies

| Feature                       | Integration Type                                   | Usage                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CL-11 (42 CFR Part 2 Consent) | Platform Integration Layer (`@/platform/clinical`) | `cl_part2_check(patient_id, scope)` SECURITY DEFINER helper gates serialization of Condition / Observation / DocumentReference resources flagged as SUD. Fail-closed if helper returns NULL. |
| GR-08 (Incident Reporting)    | Event subscriber                                   | Consumes `pm.fhir_information_blocking_logged` when disposition = `info_blocking` to open governance incident                                                                                |

**Pending IOU:** CL-11 must publish `cl.part2_consent_granted` / `cl.part2_consent_revoked` events and provide `cl_part2_check()` helper. Tracked in [`PENDING_CONTRACTS.md`](/architecture/integrations/PENDING_CONTRACTS).

***

## Events Published

| Event Name                            | Publisher | Subscribers                             | Status     |
| ------------------------------------- | --------- | --------------------------------------- | ---------- |
| `pm.fhir_app_authorized`              | PM-55     | (available — PF-04 audit)               | 📝 Planned |
| `pm.fhir_app_revoked`                 | PM-55     | (available — PF-04 audit)               | 📝 Planned |
| `pm.fhir_information_blocking_logged` | PM-55     | GR-08 (when category = `info_blocking`) | 📝 Planned |
| `pm.fhir_access_logged`               | PM-55     | PF-04 audit stream                      | 📝 Planned |

All event payloads are PHI-free (IDs + categorical fields only). See
[`EVENT_CONTRACTS.md`](/architecture/integrations/EVENT_CONTRACTS#pm-55) for schemas.

***

## Events Consumed

| Event Name                 | Source          | Usage                                                                |
| -------------------------- | --------------- | -------------------------------------------------------------------- |
| `cl.part2_consent_granted` | CL-11 (pending) | Refresh in-memory Part 2 gate cache for affected patient             |
| `cl.part2_consent_revoked` | CL-11 (pending) | Invalidate cache; subsequent FHIR reads of SUD resources fail closed |

***

## Database Tables

| Table                         | Purpose                                                          | RLS                                                                   |
| ----------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| `pm_fhir_app_registrations`   | SMART app metadata, JWKS, redirect URIs                          | Org admin manage; portal-patient read own consents only               |
| `pm_patient_access_consents`  | Patient-granted scopes per app, expiration, revocation           | Patient (portal) self-scoped; org admin read                          |
| `pm_fhir_access_log`          | Append-only access log (resource type, scope, status, timestamp) | Org admin read; INSERT-only by service role                           |
| `pm_information_blocking_log` | Exception entries with disposition workflow                      | `pm.compliance.review` to read; `pm.compliance.disposition` to update |

All tables include `organization_id`, `created_at`, `updated_at`, `custom_fields JSONB`
(except append-only audit tables — pending governance confirmation).
FK on `pm_patient_access_consents.consent_id` references `cl_consents.id`.

***

## Permissions

See spec § Permission Inventory. Constants exposed via `PM_PERMISSIONS` in
`src/platform/permissions/constants.ts`.

***

## Compliance References

* ONC HTI-1: 45 CFR 170.315(b)(11), (g)(10)
* 21st Century Cures Act §4004 — Information Blocking
* HIPAA Privacy (45 CFR 164.524) and Security (45 CFR 164.312)
* 42 CFR Part 2 — SUD confidentiality (gating via CL-11)
* US Core IG 7.0 / USCDI v3

Pending Compliance Officer signoff: `specs/pm/reviews/PM-55-COMPLIANCE-SIGNOFF.md`.