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

# Compensation Management — Integration

> Version: 1.0.0 Last Updated: 2026-03-20 Spec: HR-15 Compensation Management Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration P…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-15 Compensation Management](../../../specs/hr/specs/HR-15-compensation-management.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-15 manages compensation structures, salary bands, merit increases, and total compensation statements. It publishes events for compensation cost allocation and merit increases, and integrates with HR-07 (Payroll) and FA (Finance).

***

## Integration Points

### Platform Foundation (PF) Dependencies

**Required PF Features:**

* **PF-11 (Documents)**: Total compensation statement PDFs
* **PF-10 (Notifications)**: Merit increase notifications

### Consumer Core Dependencies (Downstream)

**Internal HR Features:**

* **HR-01 (Employee Directory)**: Employee context, current salary
* **HR-07 (Payroll)**: Salary updates, compensation data
* **HR-10 (Performance)**: Performance ratings for merit increases

**External Cores:**

* **FA (Finance)**: Compensation cost allocation to GL accounts

***

## Event Contracts

### Event: `hr_merit_increase_approved`

**Publisher:** HR (HR-15)\
**Subscribers:** HR-07 (Payroll), FA (Finance)\
**Status:** 📝 Planned

**Purpose:** Notify payroll and finance of approved merit increases

**Publish Trigger:** When `hr_merit_increases.status = 'approved'` is set

**Payload Schema:**

```typescript theme={null}
interface HrMeritIncreaseApprovedPayload {
  event_type: 'hr_merit_increase_approved';
  employee_id: uuid;
  current_salary: numeric;
  increase_percentage: numeric;
  increase_amount: numeric;
  new_salary: numeric;
  effective_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Reference:** See `docs/architecture/integrations/EVENT_CONTRACTS.md` for complete event contract documentation.

### Event: `hr_compensation_cost_allocated`

**Publisher:** HR (HR-15)\
**Subscribers:** FA (Finance)\
**Status:** 📝 Planned

**Purpose:** Map compensation data to GL accounts based on department/cost center

**Publish Trigger:** When compensation changes (real-time) or nightly batch (for bulk updates)

**Payload Schema:**

```typescript theme={null}
interface HrCompensationCostAllocatedPayload {
  event_type: 'hr_compensation_cost_allocated';
  organization_id: uuid;
  employee_id: uuid;
  total_compensation: numeric;
  base_salary: numeric;
  benefits_cost: numeric;
  effective_date: date;
  department_id: uuid;
  cost_center: string;
  timestamp: timestamptz;
}
```

**Refresh Cadence:** Real-time (published when compensation changes) or nightly batch (for bulk updates)

**FA Responsibilities:**

* Subscribe to `hr_compensation_cost_allocated` events
* Map compensation data to GL accounts based on department/cost center
* Update financial records with labor cost allocations

### Event: `hr_compensation_analysis_completed`

**Publisher:** HR (HR-15)\
**Subscribers:** FA (Finance)\
**Status:** 📝 Planned

**Purpose:** Notify finance of completed compensation analyses

**Publish Trigger:** When `hr_compensation_analyses.status = 'approved'` is set

**Payload Schema:**

```typescript theme={null}
interface HrCompensationAnalysisCompletedPayload {
  event_type: 'hr_compensation_analysis_completed';
  analysis_id: uuid;
  analysis_type: 'internal_equity' | 'market_comparison' | 'distribution';
  equity_score: number; // 0-100
  market_percentile: number; // 0-100
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Reference:** See `docs/architecture/integrations/EVENT_CONTRACTS.md` for complete event contract documentation.

### Events Consumed

#### `hr_performance_review_completed`

**Publisher:** HR-10 (Performance Management)\
**Subscriber:** HR-15 (Compensation Management)\
**Status:** 📝 Planned

**Purpose:** Trigger merit increase planning workflow when performance review is completed

**Payload Schema:** See `docs/architecture/integrations/EVENT_CONTRACTS.md` for full schema.

**Implementation Note:** The `hr_performance_review_completed` event trigger must be created in HR-10 before HR-15 can consume it.

***

## Alternative Read-Only Access (if events not used)

* FA can have read-only access to `hr_salary_bands` and `hr_total_compensation_statements` tables
* Access controlled via RLS policies using `hr_has_org_access` function
* Refresh cadence: Real-time queries or nightly batch sync

***

## Platform Integration Layer Usage

**Consumes:**

* **PF-11 (Documents)**: Total compensation statement PDFs via `@/platform/documents`
* **PF-10 (Notifications)**: Merit increase notifications via `@/platform/notifications`

***

## Security Considerations

### Multi-Tenancy

* ✅ **RLS Enforcement**: All `hr_compensation_*` and `hr_salary_*` tables filtered by `organization_id` via RLS policies

### Role-Based Access Control

* ✅ **HR Admin**: Full access to all compensation data
* ✅ **Manager**: View compensation for direct reports (if permitted)
* ✅ **Staff**: View own compensation statements only

### Data Protection

* ✅ **PII Handling**: Compensation data is highly sensitive; access controlled via RLS
* ✅ **Audit Trail**: All compensation changes logged via PF-04

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event fires on trigger condition (merit increase approval, compensation change, analysis completion)
* [ ] Correct `organization_id` included in all events
* [ ] Subscribers handle events correctly (HR-07, FA)
* [ ] RLS policies enforce org isolation on compensation queries
* [ ] Alternative read-only access works correctly if events not used

***

## References

* [HR-15 Spec](../../../specs/hr/specs/HR-15-compensation-management.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)