Skip to main content

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.

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)

​
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: 
{
  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): 
{
  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): 
{
  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

ItemBlocked OnNotes
regulatory_report_submitted event payload schemaGR-14 Phase 2 implementationGR-03 and GR-08 teams to confirm compliance evidence record format
PF-11 document metadata schema for gr_incident_regulatory_report source typePF-11 implementation statusConfirm source_type string for document generation
See PENDING_CONTRACTS.md for tracking.

​
Contract Validation

Validated against CONTRACT_VALIDATION_CHECKLIST.md:
  • Event payload schema documented (GR-14 Phase 2)
  • Publisher/subscriber declared for each event
  • Auth and tenant isolation documented per event/function
  • PHI restrictions documented (UUIDs only in event payloads)
  • Platform layer usage documented (PF-10, PF-11, PF-12)
  • Integration matrix updated in CROSS_CORE_INTEGRATIONS.md (see below)

​
References