<?php

namespace App\Services\Payroll;

/**
 * A versioned PAYE (income tax) calculation strategy. Each concrete strategy
 * encodes the tax law in force for a given period, selected by effective date,
 * so historical runs reproduce their original figures while new runs can adopt
 * newer legislation without touching old results.
 */
interface PayeStrategy
{
    /** Short identifier stored on the payroll run (e.g. "PITA"). */
    public function code(): string;

    /**
     * Compute monthly income tax from monthly figures.
     *
     * @param  float  $taxableGrossMonthly  gross of taxable earnings, monthly
     * @param  float  $pensionMonthly       employee pension contribution, monthly (tax-deductible)
     * @param  float  $nhfMonthly           NHF contribution, monthly (tax-deductible)
     * @param  float  $otherReliefMonthly   any additional monthly relief
     * @return array{tax: float, taxable_income: float, annual_tax: float, annual_taxable: float}
     */
    public function monthlyTax(
        float $taxableGrossMonthly,
        float $pensionMonthly,
        float $nhfMonthly,
        float $otherReliefMonthly = 0.0
    ): array;
}
