Final Paycheck & Termination Pay Compliance — Integration

​

Integration Overview

​

Consumed Events

​

hr_employee_terminated

interface HrEmployeeTerminatedEventEnvelope {
  event_name: 'hr_employee_terminated';
  event_id: string; // UUID for idempotency and deduplication
  timestamp: string; // ISO 8601 UTC timestamp
  metadata: {
    source: string;
    version: string;
    correlation_id?: string;
  };
  payload: HrEmployeeTerminatedPayload;
}

interface HrEmployeeTerminatedPayload {
  employee_id: string;
  organization_id: string;
  termination_date: string; // ISO date
  termination_type: 'voluntary' | 'involuntary' | 'retirement' | 'end_contract';
  offboarding_instance_id?: string | null;
}

• Deduplication key: event_id (must be unique per event instance)
• Business idempotency: Unique partial index or application check on (organization_id, employee_id, termination_date) ensures at-most-once creation of final paycheck request
• Retry behavior: Consumer must handle duplicate event_id gracefully (idempotent INSERT); retries with same event_id are no-ops
• Ordering: Events for the same employee_id should be processed in timestamp order where possible; out-of-order events are handled via business-key uniqueness check

1. Verify event_id not already processed (optional deduplication table or log check).
2. Map termination_type to HR-30 enum per spec Clarifications.
3. Insert hr_final_paycheck_requests if no row for (organization_id, employee_id, termination_date) with non-cancelled status.
4. Enqueue calculation job (status → calculating).

​

Published Events (optional Phase 2)

​

hr_final_paycheck_status_changed

interface HrFinalPaycheckStatusChangedPayload {
  event_name: 'hr_final_paycheck_status_changed';
  request_id: string;
  employee_id: string;
  organization_id: string;
  previous_status: string;
  new_status: string;
  deadline_date: string;
  timestamp: string;
}

​

HR-07 Handoff

​

Platform Integration Layer

• Use @/platform/events (or existing HR event dispatcher) for emitting/consuming typed events.
• Notifications: @/platform/notifications patterns; no PHI in notification body (ids and deadline only).

​

Security

• All access gated by RLS + hr_has_permission / is_hr_admin / hr_is_manager_of / is_self_employee per spec.
• Edge functions: verify_jwt: true; getCorsHeaders; structured logger.

​

References

• CROSS_CORE_INTEGRATIONS.md — matrix row HR-30
• EVENT_CONTRACTS.md
• CONTRACT_VALIDATION_CHECKLIST.md