CL-FW Event Automation Integration Contract

{
  event: 'cl_assessment_expired';
  publisher: 'CL';
  subscriber: ['FW'];
  payload: {
    entity_id: string;          // cl_assessments.id
    entity_type: 'assessment';
    chart_id: string;
    assessment_type: string;    // 'comprehensive', 'calocus', 'asam', 'phq9', etc.
    original_due_date: string;  // ISO date
    days_overdue: number;
    severity: 'warning';
    action_required: 'Schedule and complete reassessment';
    assigned_clinician_id: string;
  };
  metadata: {
    organization_id: string;
    user_id: string; // Use platform system profile UUID for cron (see "Automated event publishers" above)
    timestamp: string;
    correlation_id: string;
    event_id: string;
  };
}

{
  event: 'cl_moud_monitoring_overdue';
  publisher: 'CL';
  subscriber: ['FW'];
  payload: {
    entity_id: string;          // cl_moud_enrollments.id
    entity_type: 'moud_enrollment';
    chart_id: string;
    monitoring_type: string;    // 'uds', 'vital_signs', 'lab_work', 'clinical_review'
    expected_date: string;
    days_overdue: number;
    medication: string;         // 'buprenorphine', 'naltrexone', 'methadone'
    severity: 'warning';
    action_required: 'Complete overdue MOUD monitoring';
    assigned_clinician_id: string;
    care_team_ids: string[];
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

{
  event: 'cl_moud_adherence_risk';
  publisher: 'CL';
  subscriber: ['FW'];
  payload: {
    entity_id: string;          // cl_moud_enrollments.id
    entity_type: 'moud_enrollment';
    chart_id: string;
    risk_factors: string[];     // ['missed_uds', 'missed_appointment', 'dose_reduction']
    adherence_score: number;    // 0-100 scale
    threshold: number;          // Score that triggered the alert
    severity: 'critical';
    action_required: 'Urgent clinical review — MOUD adherence risk';
    assigned_clinician_id: string;
    supervisor_id: string;
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

{
  event: 'cl_care_gap_identified';
  publisher: 'CL';
  subscriber: ['FW'];
  payload: {
    entity_id: string;          // cl_care_gaps.id
    entity_type: 'care_gap';
    chart_id: string;
    gap_type: string;           // 'hedis_amm', 'hedis_fuh', 'hedis_fum', 'hedis_iet', 'preventive_screening'
    measure_id: string;         // HEDIS measure identifier
    gap_description: string;    // Human-readable (e.g., "AMM: Antidepressant medication management — acute phase")
    due_date?: string;          // Measurement year end or clinical due date
    severity: 'info';
    action_required: 'Review and close care gap';
    care_manager_id?: string;   // If attributed, assigned care manager
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

{
  event: 'cl_crisis_episode_opened';
  publisher: 'CL';
  subscriber: ['FW', 'GR'];
  payload: {
    entity_id: string;          // cl_crisis_episodes.id
    entity_type: 'crisis_episode';
    chart_id: string;
    crisis_type: string;        // 'walk_in', 'mobile', 'observation_23hr', 'phone', 'telehealth'
    risk_level: string;         // 'high' or 'imminent' (only these trigger FW)
    severity: 'critical';
    action_required: 'Crisis episode opened — immediate supervisor review';
    assigned_clinician_id: string;
    supervisor_id?: string;
  };
  metadata: { organization_id, site_id, user_id, timestamp, correlation_id, event_id };
}

{
  event: 'cl_restraint_event_initiated';
  publisher: 'CL';
  subscriber: ['GR', 'FW'];
  payload: {
    entity_id: string;              // cl_restraint_seclusion_events.id
    entity_type: 'restraint_seclusion_event';
    chart_id: string;
    event_type: string;             // e.g. 'restraint' | 'seclusion' | 'both'
    patient_age_group: string;    // e.g. 'adult' | 'adolescent' | 'child'
    max_duration_hours: number;    // Age-based regulatory limit
    initiation_time: string;       // ISO 8601
    severity: 'critical';
    action_required: string;        // e.g. 'Restraint initiated — verify monitoring and face-to-face compliance'
    crisis_episode_id?: string;
    supervisor_id?: string;
  };
  metadata: {
    organization_id: string;
    site_id?: string;
    user_id: string;
    timestamp: string;
    correlation_id: string;
    event_id: string;
  };
}

{
  event: 'cl_restraint_event_terminated';
  publisher: 'CL';
  subscriber: ['GR', 'FW'];
  payload: {
    restraint_id: string;                 // same as entity_id / cl_restraint_seclusion_events.id
    patient_id: string;                   // chart-linked patient UUID (identifier only)
    initiation_time: string;
    termination_time: string;
    termination_reason: string;
    face_to_face_required_flag: boolean;  // true if post-termination face-to-face still required
    scheduled_face_to_face_deadline?: string; // ISO 8601 — when F2F must be completed if deferred
    duration_exceeded?: boolean;
    crisis_episode_id?: string;
  };
  metadata: { organization_id, site_id?, user_id, timestamp, correlation_id, event_id };
}

{
  event: 'cl_care_gap_closed';
  publisher: 'CL';
  subscriber: ['FW'];
  payload: {
    entity_id: string;          // cl_care_gaps.id
    entity_type: 'care_gap';
    chart_id: string;
    gap_type: string;
    closure_type: string;       // e.g. service_completed, clinician_override (see CL-35)
    closed_by: string;          // pf_profiles.id (use platform system UUID for cron)
    closed_at: string;          // ISO 8601
  };
  metadata: { organization_id, user_id, timestamp, correlation_id, event_id };
}

-- Seed: CL-FW event automation registration
-- Run after FW-16 migration creates fw_workflow_events table

INSERT INTO fw_workflow_events (event_name, source_core, channel, description, auto_task_template, is_active)
VALUES
  ('cl_assessment_expired', 'CL', 'cl_events',
   'Assessment overdue — create reassessment task for clinician',
   'reassessment_reminder', true),

  ('cl_moud_monitoring_overdue', 'CL', 'cl_events',
   'MOUD monitoring overdue — alert care team and create follow-up',
   'moud_care_team_alert', true),

  ('cl_moud_adherence_risk', 'CL', 'cl_events',
   'MOUD adherence risk — escalate to supervisor with urgent review',
   'moud_escalation', true),

  ('cl_care_gap_identified', 'CL', 'cl_events',
   'Care gap identified — create task for care manager',
   'care_gap_task', true),

  ('cl_crisis_episode_opened', 'CL', 'cl_events',
   'Crisis episode opened — notify supervisor immediately',
   'crisis_supervisor_notification', true),

  ('cl_restraint_event_initiated', 'CL', 'cl_events',
   'Restraint initiated — notify GR and create incident tracking',
   'restraint_incident_creation', true),

  ('cl_restraint_event_terminated', 'CL', 'cl_events',
   'Restraint ended — update timers and close related FW tasks',
   NULL, true),

  ('cl_care_gap_closed', 'CL', 'cl_events',
   'Care gap closed — optional FW cleanup / analytics',
   NULL, true)
ON CONFLICT (event_name) DO UPDATE SET
  description = EXCLUDED.description,
  auto_task_template = EXCLUDED.auto_task_template,
  is_active = EXCLUDED.is_active;

# scripts/check-event-drift.sh
# Extract event names from pg_notify calls in CL migrations/functions
# Compare against fw_workflow_events seed INSERT statements
# Fail if any unregistered events found

// import { sanitizeErrorMessage } from '@/shared/lib/error-utils';

async function handleEvent(event: DomainEvent): Promise<void> {
  // 1. Idempotency: 0 rows must NOT throw — use maybeSingle(), not single()
  const { data: existing } = await supabase
    .from('fw_domain_events')
    .select('id')
    .eq('event_id', event.metadata.event_id)
    .maybeSingle();

  if (existing) {
    // Structured log in production — do not treat as error
    logger.info(`Duplicate event ${event.metadata.event_id} — skipping`);
    return;
  }

  try {
    await processEvent(event);
    await supabase.from('fw_domain_events').insert({
      event_id: event.metadata.event_id,
      event_name: event.event,
      correlation_id: event.metadata.correlation_id,
      status: 'processed',
      processed_at: new Date().toISOString(),
      event_payload: event as unknown as Record<string, unknown>, // full payload for audit / replay
    });
  } catch (err) {
    await supabase.from('fw_domain_events').insert({
      event_id: event.metadata.event_id,
      event_name: event.event,
      correlation_id: event.metadata.correlation_id,
      status: 'failed',
      retry_count: 0,
      error_message: sanitizeErrorMessage(err),
      processed_at: null,
      event_payload: event as unknown as Record<string, unknown>,
    });
    throw err;
  }
}