CL–GR: Clinical Incident Bridge Integration

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.

​

Purpose

​

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

​

Purpose

​

Trigger Conditions

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

​

Payload Schema

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;
}

​

Event 2: cl_restraint_event_documented

​

Purpose

​

Trigger Conditions

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

​

Payload Schema

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;
}

​

Event 3: gr_incident_created

​

Purpose

​

Payload Schema

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;
}

​

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 — add all three events
• 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