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

# Regulatory Incident Reporting Automation — Integration Contract

> Feature ID: GR-14 Spec: GR-14 Regulatory Incident Reporting Automation Version: 1.0 Status: ✅ Complete Last Updated: 2026-03-07 Owner: GR (Governance & Risk)

**Feature ID:** GR-14\
**Spec:** [GR-14 Regulatory Incident Reporting Automation](../../../specs/gr/specs/GR-14-regulatory-incident-reporting-automation.md)\
**Version:** 1.0\
**Status:** ✅ Complete\
**Last Updated:** 2026-03-07\
**Owner:** GR (Governance & Risk)

***

## Overview

GR-14 implements the regulatory reporting automation layer on top of GR-09 (Incident Reporting). It automatically classifies incidents against statutory reporting rules, tracks deadlines, generates report packages, and notifies compliance staff.

**Integration patterns used:**

* **Event Consumer:** Subscribes to `incident_created` (channel: `gr_events`, ✅ Implemented) from GR-09
* **Event Publisher:** Publishes `regulatory_report_submitted` consumed by GR-03, GR-08, PF-10
* **Platform Layer:** PF-10 (Notifications), PF-11 (Documents), PF-12 (Reporting), PF-30 (Permissions)

***

## Integration 1: GR-09 → GR-14 (Event Consumer)

### Event: `incident_created`

**Channel:** `gr_events`\
**Publisher:** GR-09 (Incident Reporting)\
**Consumer:** GR-14 (`gr-classify-incident-reporting-obligations` edge function)\
**Status:** ✅ Implemented — trigger emits for ALL incidents

**Payload consumed by GR-14:**

```typescript theme={null}
{
  event_type: 'incident_created';
  organization_id: uuid;
  timestamp: timestamptz;
  site_id?: uuid;
  incident_id: uuid;
  chart_id?: uuid;          // when incident is patient-related
  // Additional fields from gr_incidents available via DB lookup:
  // category, severity, incident_date, custom_fields
}
```

**GR-14 action on receipt:**

1. Fetch `gr_incidents` row for `incident_id` to get `category`, `severity`, `incident_date`, `custom_fields`
2. Evaluate all active `gr_regulatory_reporting_rules` for `organization_id` (system-wide + org-specific)
3. For each matching rule: calculate `statutory_deadline` per `deadline_type` (calendar or business hours)
4. Insert `gr_incident_regulatory_reports` rows (UNIQUE constraint prevents duplicates)

**Edge Function:** `supabase/functions/gr-classify-incident-reporting-obligations/index.ts`\
**Auth:** `verify_jwt: false` (server-to-server via `pg_net`; validates via service role key in `Authorization` header, NOT `verifyOrgAccess()` which expects a user JWT)

***

## Integration 2: GR-14 → GR-03, GR-08, PF-10 (Event Publisher)

### Event: `regulatory_report_submitted`

**Channel:** `gr_events`\
**Publisher:** GR-14 (on `status → submitted` transition)\
**Subscribers:** GR-03 (compliance evidence), GR-08 (accreditation evidence), PF-10 (notification)\
**Status:** ✅ Implemented

**Payload (stub — finalize on implementation):**

```typescript theme={null}
{
  event_type: 'regulatory_report_submitted';
  organization_id: uuid;
  timestamp: timestamptz;
  regulatory_report_id: uuid;
  incident_id: uuid;
  regulatory_body: 'AHCCCS' | 'APS' | 'DCS' | 'CMS' | 'CARF' | 'Joint Commission' | 'Other';
  regulation_citation: string;
  submitted_at: timestamptz;
  submitted_by: uuid;
  agency_reference_number?: string;
}
```

**Pending:** Event payload schema to be finalized during GR-14 Phase 2 implementation. GR-03 and GR-08 teams to confirm compliance evidence record format.

***

## Integration 3: GR-14 → PF-10 (Platform Layer — Notifications)

**Pattern:** Platform Integration Layer (PF-10)\
**Usage:** Deadline D-N and overdue alerts sent to users with `incident_regulatory_reports.view` permission\
**Function:** `createNotificationIfNew()` from `supabase/functions/_shared/notification-utils.ts`\
**Called by:** `gr-regulatory-deadline-alerts` cron edge function

**Notification types:**

* `gr_regulatory_deadline_approaching`: Sent `deadline_notification_days_before` days before `statutory_deadline`
* `gr_regulatory_deadline_overdue`: Sent daily while `now() > statutory_deadline AND status IN ('draft', 'ready')`

***

## Integration 4: GR-14 → PF-11 (Platform Layer — Documents)

**Pattern:** Platform Integration Layer (PF-11)\
**Usage:** Regulatory report packages stored as PF documents\
**Called by:** `gr-generate-regulatory-report` edge function\
**Output:** `report_document_id` UUID linked on `gr_incident_regulatory_reports`

**Document metadata (stub):**

```typescript theme={null}
{
  document_type: 'regulatory_report';
  source_id: regulatory_report_id;
  source_type: 'gr_incident_regulatory_report';
  organization_id: uuid;
  generated_at: timestamptz;
}
```

***

## Integration 5: GR-14 → PF-12 (Platform Layer — Reporting)

**Pattern:** Platform Integration Layer (PF-12)\
**Usage:** Regulatory reporting summary report for accreditation/audit purposes\
**Status:** 📝 Planned — Phase 3

***

## Security & Tenant Isolation

* All GR-14 tables RLS-filtered by `organization_id`
* SECURITY DEFINER helpers `gr_has_org_access()` / `gr_is_org_admin()` used exclusively in RLS policies
* PHI in `narrative` column: access gated by `incident_regulatory_reports.view` permission
* Event payloads contain patient identifiers (`chart_id`) as UUIDs; subscribing functions must enforce RLS and appropriate patient access controls
* `gr-classify-incident-reporting-obligations`: runs as `service_role` (bypasses RLS by design); performs explicit `organization_id` validation before inserting regulatory reports. Because service-role bypasses RLS, the function must independently verify the caller's org membership and the incident's organization context before any writes

***

## Pending Contract Items

| Item                                                                           | Blocked On                   | Notes                                                              |
| ------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------ |
| `regulatory_report_submitted` event payload schema                             | GR-14 Phase 2 implementation | GR-03 and GR-08 teams to confirm compliance evidence record format |
| PF-11 document metadata schema for `gr_incident_regulatory_report` source type | PF-11 implementation status  | Confirm `source_type` string for document generation               |

See [PENDING\_CONTRACTS.md](./PENDING_CONTRACTS.md) for tracking.

***

## Contract Validation

Validated against [CONTRACT\_VALIDATION\_CHECKLIST.md](./CONTRACT_VALIDATION_CHECKLIST.md):

* [ ] Event payload schema documented (GR-14 Phase 2)
* [x] Publisher/subscriber declared for each event
* [x] Auth and tenant isolation documented per event/function
* [x] PHI restrictions documented (UUIDs only in event payloads)
* [x] Platform layer usage documented (PF-10, PF-11, PF-12)
* [ ] Integration matrix updated in CROSS\_CORE\_INTEGRATIONS.md (see below)

***

## References

* [GR-14 Spec](../../../specs/gr/specs/GR-14-regulatory-incident-reporting-automation.md)
* [GR-09 Spec](../../../specs/gr/specs/GR-09-incident-reporting.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) — `incident_created` event
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md) — PF-10, PF-11, PF-12
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)