> ## 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: Clinical Incident Bridge Integration

> Status: 📝 Planned Created: 2026-03-02 Source: specs/cl/CL-STRATEGIC-ROADMAP-20260302.md Constitution Reference: Section 1.3 (Integration Patterns); no direct…

**Status:** 📝 Planned\
**Created:** 2026-03-02\
**Source:** [specs/cl/CL-STRATEGIC-ROADMAP-20260302.md](../../../specs/cl/CL-STRATEGIC-ROADMAP-20260302.md)\
**Constitution Reference:** Section 1.3 (Integration Patterns); no direct core-to-core imports.

***

## Purpose

When a critical clinical event occurs (safety plan activation, restraint/seclusion when CL-13 is built, patient elopement, adverse medication event), there should be an automated path to create or link to an incident report in GR-08. Conversely, when GR records a critical incident, the clinical chart should be flagged for open documentation. This bi-directional bridge supports AHCCCS AMPM 1620-O (critical incident reporting), Joint Commission, and CARF requirements.

**Regulatory driver:** AHCCCS AMPM Policy 1620-O; ARS 46-454 (vulnerable adult reporting); 42 CFR 482.13; CARF; Joint Commission EC.04.01.01.

***

## Integration Type

* **Event-based (CL → GR):** CL publishes when safety plan is activated or restraint/seclusion is documented; GR-08 subscribes and creates draft incident report.
* **Event-based (GR → CL):** GR publishes when incident is created; CL subscribes and flags chart with “open documentation requirement” or similar.

***

## Event Contracts

### Event 1: `cl_safety_plan_activated`

**Event:** `cl_safety_plan_activated`\
**Channel:** `cl_events`\
**Publisher:** CL (CL-07 Suicide Risk Screening & Safety Planning)\
**Subscribers:** GR (GR-08 Incident Reporting)\
**Status:** 📝 Planned

#### Purpose

When a safety plan is activated (e.g. crisis intervention, escalation), GR can create or link a draft incident report for compliance tracking.

#### Trigger Conditions

* Application or clinician marks safety plan as “activated” in CL-07 workflow.

#### Payload Schema

```typescript theme={null}
interface ClSafetyPlanActivatedPayload {
  event_type: 'cl_safety_plan_activated';
  organization_id: uuid;
  timestamp: timestamptz;
  site_id?: uuid;
  user_id?: uuid;
  chart_id: uuid;
  safety_plan_id?: uuid;
  encounter_id?: uuid;
  correlation_id?: uuid;
}
```

**PHI restrictions:** Only include identifiers (UUIDs). Do NOT include patient names, SSN, DOB, addresses, clinical details, or other direct PHI elements.\
**correlation\_id:** Use to link related events across the CL–GR bridge for distributed tracing and audit trails.

| Consumer | Action                                                                                   | Status     |
| -------- | ---------------------------------------------------------------------------------------- | ---------- |
| GR-08    | Create draft incident report; link to chart/safety plan; type = safety\_plan\_activation | 📝 Planned |

***

### Event 2: `cl_restraint_event_documented`

**Event:** `cl_restraint_event_documented`\
**Channel:** `cl_events`\
**Publisher:** CL (CL-13 Crisis Intervention Documentation when implemented)\
**Subscribers:** GR (GR-08)\
**Status:** 📝 Planned

#### Purpose

When restraint or seclusion is documented per 42 CFR 482.13(e), GR receives event and creates or links incident report.

#### Trigger Conditions

* Restraint or seclusion event is documented in CL-13.

#### Payload Schema

```typescript theme={null}
interface ClRestraintEventDocumentedPayload {
  event_type: 'cl_restraint_event_documented';
  organization_id: uuid;
  timestamp: timestamptz;
  site_id?: uuid;
  user_id?: uuid;
  chart_id: uuid;
  encounter_id?: uuid;
  restraint_type: 'restraint' | 'seclusion';
  correlation_id?: uuid;
}
```

**PHI restrictions:** Only include identifiers (UUIDs). Do NOT include patient names, SSN, DOB, addresses, clinical details, or other direct PHI elements.\
**correlation\_id:** Use to link related events across the CL–GR bridge for distributed tracing and audit trails.

| Consumer | Action                                                                   | Status     |
| -------- | ------------------------------------------------------------------------ | ---------- |
| GR-08    | Create draft incident report; link to chart; type = restraint\_seclusion | 📝 Planned |

***

### Event 3: `gr_incident_created`

**Event:** `gr_incident_created`\
**Channel:** `gr_events` (or equivalent)\
**Publisher:** GR (GR-08)\
**Subscribers:** CL (chart flag for open documentation)\
**Status:** 📝 Planned

#### Purpose

When a critical incident is created in GR that relates to a patient/chart, CL can flag the chart so clinicians see an “open documentation requirement” or “related incident” indicator.

#### Payload Schema

```typescript theme={null}
interface GrIncidentCreatedPayload {
  event_type: 'gr_incident_created';
  organization_id: uuid;
  timestamp: timestamptz;
  site_id?: uuid;
  incident_id: uuid;
  chart_id?: uuid;   // when incident is patient-related
  incident_type?: string;
  correlation_id?: uuid;
}
```

**PHI restrictions:** Only include identifiers (UUIDs). Do NOT include patient names, SSN, DOB, addresses, clinical details, or other direct PHI elements.\
**correlation\_id:** Use to link related events across the CL–GR bridge for distributed tracing and audit trails.

| Consumer | Action                                                                                                                   | Status     |
| -------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| CL       | Set or display chart-level flag “open documentation required” or “related incident”; link to incident\_id for navigation | 📝 Planned |

***

## Implementation Notes

* **CL:** Emit `cl_safety_plan_activated` from CL-07 when plan activated; emit `cl_restraint_event_documented` from CL-13 when restraint/seclusion documented. Subscribe to `gr_incident_created` and set chart flag (table or custom\_fields).
* **GR:** Subscribe to CL events; create draft incident with reference to chart\_id/safety\_plan\_id/encounter\_id. Emit `gr_incident_created` when incident is created; include chart\_id when applicable.
* **Event registry:** Add all three events to EVENT\_CONTRACTS.md and fw\_workflow\_events as needed. Document security and retry expectations in those artifacts.

### Security, Tenant Isolation, and Resilience

* **Tenant validation:** Event consumers **must** perform server-side tenant validation. Client-side checks alone are insufficient; RLS policies and explicit server-side checks are mandatory. Implement a `SECURITY DEFINER` stored procedure (e.g. `validate_and_write_incident` or `apply_incident_event`) that: (1) reads the authenticated tenant from the DB session via `current_setting('jwt.claims.organization_id')` (or equivalent); (2) compares it to the incoming event payload `organization_id`; (3) raises/aborts on mismatch. After validation, the function must switch to a least-privileged DB role (e.g. `SET LOCAL ROLE` to a role that has only the minimum privileges needed for the write) before performing any inserts/updates so RLS policies and least-privilege semantics are preserved. All event consumers (CL and GR) that write to tables must use this pattern.
* **Encryption and audit logging:** Log timestamp, user\_id, organization\_id for event emissions and consumptions on event channels.
* **Least-privilege:** Pub/sub subscriptions must use least-privilege access controls; consumers must not have broad table access beyond what the event contract requires.
* **Error handling:** Use exponential backoff retries for transient failures; implement a dead-letter queue for events that exceed max retry count; ensure durable/persisted replayability when consumers are temporarily unavailable.
* **Event names:** `cl_safety_plan_activated`, `cl_restraint_event_documented`, `gr_incident_created` — update EVENT\_CONTRACTS.md and fw\_workflow\_events to include these security and retry expectations.

***

## Testing Requirements

* [ ] cl\_safety\_plan\_activated payload valid; GR consumer creates draft incident
* [ ] cl\_restraint\_event\_documented payload valid; GR consumer creates draft incident
* [ ] gr\_incident\_created payload valid; CL consumer sets chart flag
* [ ] No PHI in payloads beyond ids; tenant isolation in all consumers
* [ ] **PHI in payload:** Payloads containing unexpected PHI — assert consumers strip or reject PHI (cl\_safety\_plan\_activated, cl\_restraint\_event\_documented, gr\_incident\_created handlers)
* [ ] **Tenant isolation:** Tenant isolation breach attempts and multi-tenant boundary tests; no cross-tenant visibility
* [ ] **Malformed payloads:** Malformed or partial payloads; retry/failure handling for GR and CL consumers
* [ ] **Downstream failures:** Simulated downstream service failures and timeouts; verify graceful degradation and backoff
* [ ] **Audit/logging:** gr\_incident\_created and draft incident creation (from cl\_safety\_plan\_activated / cl\_restraint\_event\_documented) produce immutable audit entries with sufficient metadata (actor, timestamp, request id)

***

## References

* [EVENT\_CONTRACTS.md](EVENT_CONTRACTS.md) — add all three events
* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)
* specs/cl/CL-07-suicide-risk-screening-safety-planning.md
* specs/cl/CL-13-crisis-intervention-documentation.md
* specs/cl/CL-STRATEGIC-ROADMAP-20260302.md