> ## 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–GR–PM: BHRF Clinical Residential Episode Lifecycle Integration

> BHRF clinical residential episode lifecycle (A.A.C. R9-10-701..722) coordinated via events across RH, CL-68, PM-74, GR-27. No cross-core imports.

**Status:** 📝 Planned
**Created:** 2026-05-18
**Source:** BHRF Coverage Plan 2026-05-18 (deep review of CL vs. `docs/archive/ehr_pm/ehr_research_updated.md` — A.A.C. R9-10-701 to R9-10-722)
**Constitution Reference:** Section 1.3 (Integration Patterns); no direct core-to-core imports. CL is architecturally downstream — GR/PM MUST NOT depend on CL.

***

## Purpose

A Behavioral Health Residential Facility (BHRF) is a **licensed clinical residential level of care** (A.A.C. R9-10-701–722, adult subclass) — distinct from non-clinical recovery housing (RH core). The BHRF lifecycle inherently spans four cores, and the constitution forbids a dedicated "BHRF core" or cross-core imports. This contract defines the events and platform layer that let those cores coordinate **without** direct imports or cross-core foreign keys:

* **RH (RH-01.1):** owns the residence + bed/census substrate. On a `psychiatric_residential` admission it publishes the admission event. RH stays non-clinical.
* **CL (CL-68):** consumes the admission event, opens the clinical residential episode, drives the 15-day comprehensive-assessment requirement + level-of-care, and publishes clinical-milestone events. Reuses CL-02/CL-49/CL-03/CL-04/CL-13-EN-01/CL-29.
* **PM (PM-74):** consumes RH admission/census events for per-diem (H0018/H0019/T2048, POS 56) and applies the AHCCCS BHRF 5-day urgent exemption + continued-stay authorization; hands continued-stay review to CL-43 via event.
* **GR (GR-27):** consumes residence/clinical events for the non-clinical regulatory layer (R9-10 licensure, staffing minimums, incident timeframes, retention) and the GR compliance dashboard.

**Regulatory driver:** A.A.C. R9-10-701–722 (BHRF, adult); AHCCCS AMPM 320-O / 940 (assessment, plan, progress notes — reused via CL-02/03/04); AHCCCS prior-authorization rules (BHRF 5-day urgent exemption + continued stay); A.R.S. § 46-454 / § 13-3620 (mandatory reporting); A.R.S. § 12-2297 (record retention); **42 CFR Part 2** — SUD-identifying context must be gated through CL-11 consent/disclosure policy before any cross-core emission.

***

## Integration Type

* **Event-based:** RH publishes admission/discharge; CL-68 publishes clinical milestones; PM-74 publishes the continued-stay handoff; GR-27 publishes compliance findings.
* **Platform layer:** `getResidentialEpisodeContext()` lets PM/GR read episode/LOC context without querying CL tables; `@/platform/jurisdiction` (PF-96) supplies state-variable windows; `@/platform/workforce` supplies credential/supervision facts to GR-27.

***

## Cross-core boundary invariants

* **No core-to-core imports.** All cross-core state flows via `fw_domain_events` or platform layers.
* **CL is downstream.** GR-27 and PM-74 consume CL-68 events but **do not list CL-68 as a dependency**. CL-68 references CL-62 only as a future consolidation target (not a dependency).
* **No cross-core foreign keys.** `residence_ref` / `chart_ref` on CL/GR/PM tables carry id *values* from event payloads; referential integrity is asserted by the event contract + tests, not a DB FK. (ADR-002 covers only the CL→PM encounter FK exception, not used here.)
* **Restraint/seclusion split:** clinical mechanics (order, age-band time limits, ≤1h face-to-face, monitoring, debriefing) = **CL-13-EN-01** (reused by CL-68 via episode link); the 24-hour restraint-with-injury *reporting obligation* = **GR-27**; clinical incident *capture* = CL-15. No duplication.

***

## Event Contract

### Event: `rh_psychiatric_residential_admission`

> **Canonical source / alias mapping:** RH-01.1's authoritative lifecycle event is the canonical **`rh_resident_admitted`** (it already carries `facility_type`). `rh_psychiatric_residential_admission` is a **logical alias** used throughout this contract for "`rh_resident_admitted` filtered to `facility_type = 'psychiatric_residential'`". Consumers (CL-68, PM-74, GR-27) subscribe to the canonical `rh_resident_admitted` / `rh_resident_discharged` events and filter by `facility_type`; no new RH event is introduced (RH-01.1 canonical names are authoritative; no non-canonical RH events are defined outside RH).

**Channel:** `rh_events` (RH lifecycle). Consumers filter by `facility_type = 'psychiatric_residential'`.
**Publisher:** RH (RH-01.1 — canonical `rh_resident_admitted`)
**Subscribers:** CL (CL-68 open episode), PM (PM-74 per-diem + 5-day exemption), GR (GR-27 license/staffing applicability)
**Status:** 📝 Planned

#### Purpose

Signal that a resident was admitted to a `psychiatric_residential` (BHRF/RTC) residence so clinical, billing, and compliance lifecycles can begin.

#### Trigger Conditions

* INSERT of an RH episode/admission where `rh_residences.facility_type = 'psychiatric_residential'`.

#### Payload Schema

```typescript theme={null}
interface RhPsychiatricResidentialAdmissionPayload {
  event_id: string;              // UUID — canonical dedupe key (required for at-least-once)
  event_type: 'rh_resident_admitted'; // canonical RH-01.1 event; BHRF = filter facility_type='psychiatric_residential'
  organization_id: uuid;
  timestamp: timestamptz;
  residence_id: uuid;          // rh_residences.id (carried as a value; no cross-core FK)
  chart_id: uuid;              // patient chart id
  site_id?: uuid;
  admitted_at: timestamptz;
  facility_type: 'psychiatric_residential';
  urgency?: 'urgent' | 'routine';   // drives PM-74 5-day exemption
  correlation_id?: uuid;
}
```

#### Consumer Actions

| Consumer | Action                                                                                                                                          |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| CL-68    | Open `cl_bhrf_episodes`; compute `assessment_due_date`/`initial_plan_due_date` from PF-96; idempotent on (org, chart, residence, admitted\_at). |
| PM-74    | Begin per-diem day ledger; if `urgency='urgent'`, mark days 1..N PA-exempt (PF-96).                                                             |
| GR-27    | Ensure a `gr_bhrf_licenses` + `gr_bhrf_staffing_requirements` record exists for the residence; else raise a finding.                            |

#### Operational Requirements

* Idempotent (replay-safe) per consumer; at-least-once delivery; payload `event_type` versioned.

#### Security and Compliance

* No clinical narrative in payload. SUD-identifying context excluded; any later SUD context emission gated by CL-11. Audit on consumption.

***

### Event: `cl_bhrf_loc_determined`

**Channel:** `cl_events` (single canonical channel — PM-74/GR-27 subscribe here; no dual-publish to alternate channels).
**Publisher:** CL (CL-68)
**Subscribers:** PM (PM-74 authorization matching), GR (GR-27 dashboard)
**Status:** 📝 Planned

#### Purpose

Notify that a level-of-care determination was recorded on the BHRF clinical episode (basis for continued-stay authorization and compliance).

#### Trigger Conditions

* LOC recorded on `cl_bhrf_episodes` (sourced from CL-49 / CL-02).

#### Payload Schema

```typescript theme={null}
interface ClBhrfLocDeterminedPayload {
  event_id: string;              // UUID — canonical dedupe key (required for at-least-once)
  event_type: 'cl_bhrf_loc_determined';
  organization_id: uuid;
  timestamp: timestamptz;
  episode_id: uuid;
  chart_id: uuid;
  site_id?: uuid;
  loc_value: string | null;    // coded level (e.g. 'ASAM 3.5'); null (redacted, not omitted) when CL-11 SUD consent absent/revoked
  determined_at: timestamptz;
  correlation_id?: uuid;
}
```

#### Consumer Actions

| Consumer | Action                                                   |
| -------- | -------------------------------------------------------- |
| PM-74    | Associate LOC with continued-stay authorization context. |
| GR-27    | Increment BHRF compliance dashboard counters.            |

#### Security and Compliance

* `loc_value` is a coded level, not narrative. If LOC implies SUD treatment, emission is gated by CL-11 consent policy (42 CFR Part 2 §2.31/2.32).

***

### Event: `cl_bhrf_clinical_assessment_completed`

**Channel:** `cl_events`
**Publisher:** CL (CL-68)
**Subscribers:** GR (GR-27 timeliness compliance), PM (PM-74, optional)
**Status:** 📝 Planned

#### Purpose

Notify that the comprehensive clinical assessment requirement for the BHRF episode was satisfied (supports the 15-day timeliness compliance view).

#### Payload Schema

```typescript theme={null}
interface ClBhrfClinicalAssessmentCompletedPayload {
  event_id: string;              // UUID — canonical dedupe key (required for at-least-once)
  event_type: 'cl_bhrf_clinical_assessment_completed';
  organization_id: uuid;
  timestamp: timestamptz;
  episode_id: uuid;
  chart_id: uuid;
  site_id?: uuid;
  completed_at: timestamptz;
  correlation_id?: uuid;
}
```

#### Consumer Actions

| Consumer | Action                                                           |
| -------- | ---------------------------------------------------------------- |
| GR-27    | Mark assessment-timeliness compliance for the residence/episode. |

***

### Event: `pm_bhrf_continued_stay_review_required`

**Channel:** `cl_pm_events` (encounter/authorization-scoped review handoff).
**Publisher:** PM (PM-74)
**Subscribers:** CL (CL-43 Concurrent Review / Utilization Management)
**Status:** 📝 Planned

#### Purpose

Hand off continued-stay/concurrent review when authorized BHRF days are exhausted or expiring.

#### Payload Schema

```typescript theme={null}
interface PmBhrfContinuedStayReviewRequiredPayload {
  event_id: string;              // UUID — canonical dedupe key (required for at-least-once)
  event_type: 'pm_bhrf_continued_stay_review_required';
  organization_id: uuid;
  timestamp: timestamptz;
  chart_ref: uuid;
  residence_ref: uuid;
  authorization_id: uuid;
  remaining_days: number;
  expires_on?: date;
  correlation_id?: uuid;
}
```

#### Consumer Actions

| Consumer | Action                                                            |
| -------- | ----------------------------------------------------------------- |
| CL-43    | Create a concurrent-review task for continued-stay justification. |

> PM-74 publishes this event; it does **not** import CL-43. CL-43 is the downstream consumer.

***

### Event: `gr_bhrf_compliance_finding_raised`

**Channel:** `gr_events`
**Publisher:** GR (GR-27)
**Subscribers:** PF notifications/dashboards
**Status:** 📝 Planned

#### Purpose

Surface a BHRF regulatory finding (missing license, staffing gap, incident-timeframe risk, retention gap).

#### Payload Schema

```typescript theme={null}
interface GrBhrfComplianceFindingRaisedPayload {
  event_id: string;              // UUID — canonical dedupe key (required for at-least-once)
  event_type: 'gr_bhrf_compliance_finding_raised';
  organization_id: uuid;
  timestamp: timestamptz;
  residence_ref: uuid;
  finding_type: 'missing_license' | 'staffing_gap' | 'incident_timeframe' | 'retention_gap';
  due_at?: timestamptz;
  correlation_id?: uuid;
}
```

***

## Platform Integration Layer

### API: `getResidentialEpisodeContext`

* **Provider:** CL (CL-68) via `@/platform/clinical` (or `@/platform/residential` facade)
* **Consumers:** PM-74 (authorization context), GR-27 (compliance counters)
* **Scope:** organization + episode; SECURITY DEFINER RPC; returns coded context only (episode status, LOC code, assessment-complete flag, due dates) — **no clinical narrative**, no direct CL table access by consumers.
* **Tenant authorization (mandatory):** the SECURITY DEFINER RPC MUST validate the caller's membership/role on the supplied `organizationId` (e.g. `pf_has_org_access`) **before any lookup** — parameter scoping alone is not a tenant boundary. Error contract is **authoritatively defined in [`API_CONTRACTS.md` → CL-68: Residential Episode Context](./API_CONTRACTS.md)** and consumers MUST follow it: caller not org-authorized for `organizationId` → **403** (decided pre-lookup); caller org-authorized but `episodeId` not found within that tenant scope → **top-level `null`** (existence not revealed); top-level `null` is never used for an authorization failure. Every denied-access attempt (403) and every Part 2 redaction MUST produce an audit-log entry per §2.31. PM-74/GR-27 must expect authorization-enforced `locValue` nulling + audit.
* **42 CFR Part 2 conditional behavior:** the function still returns the context object (it returns `null` only when the episode itself is inaccessible/not found). When CL-11 consent for SUD-implying LOC is **absent or revoked**, `locValue` is **redacted to `null`** (not omitted) and the access is audit-logged per 42 CFR Part 2 §2.31. Consumers PM-74 and GR-27 MUST handle `locValue === null` as "LOC not disclosable" — no fallback guessing.

```typescript theme={null}
// @/platform/clinical
export async function getResidentialEpisodeContext(params: {
  organizationId: string;
  episodeId: string;
}): Promise<{
  status: 'pending' | 'clinically_active' | 'discharged' | 'cancelled';
  locValue: string | null;        // null when CL-11 SUD consent absent/revoked (redacted, not omitted)
  assessmentCompleted: boolean;
  assessmentDueDate: string;
  initialPlanDueDate: string;
} | null>;                        // null only if the episode is inaccessible/not found
```

### PF-96 jurisdiction (`@/platform/jurisdiction`)

Supplies state-variable values: `bhrf_comprehensive_assessment_days`, `bhrf_initial_plan_days`, `bhrf_plan_update_days`, `bhrf_urgent_pa_exempt_days`, `bhrf_concurrent_review_threshold_days`, `bhrf_clinical_director_capacity_threshold`, `bhrf_incident_timeframe[category]`, `bhrf_record_retention_years`.

### Platform workforce (`@/platform/workforce`)

Supplies BHP/BHT/RN/clinical-director credential & supervision facts to GR-27 (no HR import).

***

## Implementation Notes

* Each consumer must be idempotent and replay-safe; key per-diem day generation on `(org, residence_ref, chart_ref, service_date)`, episode open on `(org, chart, residence, admitted_at)`.
* `residence_ref`/`chart_ref` are id values from payloads — never add a DB FK across cores.
* Feature flags per spec: `cl.bhrf.enabled`, `pm.residential_perdiem.enabled`, `gr.bhrf.enabled`.
* Until PF-96 ships, consumers fall back to Arizona-default seeds; specs are 🛑 Blocked in Phase 0 dependency check until PF-96 — expected and documented in each spec's Dependencies line.

## Testing Requirements

* Payload schema validation for all BHRF events — the five lifecycle events plus `pm_residential_charge_held` (required fields, `event_id`, `event_type`); duplicate `event_id` is processed as success (idempotent), transient errors retried per R7 backoff, fatal errors dead-lettered.
* Fire-on-admission: a `psychiatric_residential` admission opens a CL-68 episode, starts PM-74 per-diem, and ensures a GR-27 license/staffing record (or finding).
* Idempotent refetch/replay: duplicate events do not duplicate episodes/day-charges/findings.
* RLS / tenant isolation across CL/PM/GR tables (Org A cannot read Org B).
* 42 CFR Part 2 (events): SUD-context redaction/gating on `cl_bhrf_loc_determined`; consent revocation respected; audit entries created.
* 42 CFR Part 2 (platform layer): `getResidentialEpisodeContext` returns `locValue: null` (redacted, not omitted) when CL-11 SUD consent is absent/revoked; the context object is still returned; each access is logged/audited per §2.31; PM-74/GR-27 handle `locValue === null` without fallback guessing.
* CL-downstream check: no GR/PM build-time dependency on CL-68; cross-core path is events/platform-layer only.

## References

* Specs: [CL-68](../../../specs/cl/specs/CL-68-bhrf-clinical-residential-program-documentation.md), [GR-27](../../../specs/gr/specs/GR-27-bhrf-facility-licensure-staffing-compliance.md), [PM-74](../../../specs/pm/specs/PM-74-residential-per-diem-billing-bhrf-authorization.md)
* Reused: CL-02, CL-03, CL-04, CL-13-EN-01, CL-29, CL-43, CL-49; PM-07, PM-10; RH-01.1; PF-46, PF-96
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md) — matrix row
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) — event schemas
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md) — platform layer
* Regulatory: `docs/archive/ehr_pm/ehr_research_updated.md`; `docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md`
* Constitution `constitution.md` §1.3 (Integration Patterns), ADR-002 (CL→PM FK exception — not used here)