# Annual leave allocations — September 6, 2026

NEW: Leave Configuration → General Rules → Leave year & credits now supports
annual allocation rules, an employee preview, reviewed bulk posting, and saved
batch snapshots. Company policy and entitlement/ledger migrations are required.
This phase uses calendar years (January–December), with HR-triggered posting.

## Rules and calculations

Select an immutable company policy version, starting year, and allocation method:

- **Full annual amount:** the selected policy allowance once the employee is eligible.
- **Prorate by eligible calendar days:** allowance multiplied by eligible days
  through December 31, divided by days in that calendar year. Include the first
  eligible day and round to two decimal places. Leap years use 366 days.
- **Prorate by completed service months:** allowance multiplied by completed
  service months, capped at 12, divided by 12. Rerunning after a new milestone
  offers only the difference between the earned target and existing credits.

The eligible start is the latest of January 1, the policy's effective date, and
the date the employee completes the required service months from hire date.
Completed months follow the request policy's TIMESTAMPDIFF behavior: for example,
January 31 plus one completed month becomes March 1 in a non-leap year.
Every allocation requires a valid hire date, even when minimum service is zero.

Rules apply from their starting year until superseded by a rule starting in a
later year for the same company/brand/type. Saving a new rule never grants credits.
The policy version is explicitly pinned; publishing a different company policy
does not silently rewrite this allocation rule or already-posted credits.

**Additional grant = max(0, annual target − existing total credits).** Used days
are not subtracted from existing credits for this calculation: doing so would
incorrectly replenish consumed leave. Manual and opening credits count toward
the target. Existing credits above the target are never reduced automatically.
Opening-unverified balances remain labeled as such in the preview.

## Exclusions and posting

The preview lists ready and excluded employees with reasons. Exclusions include
inactive employees, invalid/missing hire dates, future eligibility, deferred
reconciliation, account ownership mismatches, approved history without a balance,
and annual allocations already posted for that employee/type/year.

Previewing does not create accounts or write credits. It uses the current Manila
date; employees who become eligible later can be included by rerunning then.
Future years may be previewed but cannot be posted before that year starts.
Prior years are only available if a saved rule actually covers them; rule creation
itself does not permit backdating before the current year.

HR reviews the rows and checks the acknowledgment before posting. The server
recomputes the preview under a transaction and compares its fingerprint, including
employee information, current credits/usage, review status, rule and calculation
date. Changed data requires a fresh review; the client cannot supply grant amounts.
The batch uses serializable transactions with employee, brand and balance locks.

All ready rows post in one transaction through the existing credit-grant service;
it participates in the caller's transaction without committing individual grants.
Any failure rolls back the entire batch. No second ledger/balance writer is added.
A unique batch fingerprint handles request retries. A stable employee/type/year
grant key and unique allocation item prevent repeated annual allocations even
across different rule versions. Reversing a posted grant in Leave Balance does
not make the allocator re-grant it; intentional corrections use explicit manual
credit actions. Each grant reason references its allocation rule and batch.

The last 25 batches are visible in General Rules. Each opens its preserved preview,
including exclusions. Individual grants and reversals remain available in the
employee ledger. Each preview is capped at 1,000 employees in the selected brand.

## Permissions

- Rule access requires admin authentication, selected-brand access and `leave_type`.
- Rule creation also requires `can_add`.
- Employee previews and batch history additionally require `leave_balances`.
- Posting requires both modules and `can_add`; a user with only read permissions
  can inspect a preview but cannot post credits. Client-portal callers are denied.

## Rollout

1. Test a clone and keep the existing backup/reconciliation reports.
2. Select the intended database and run
   `backend/migrations/2026_09_06_leave_annual_allocations.sql`, followed by
   `backend/migrations/2026_09_08_leave_service_month_accrual.sql`. These
   additive migrations do not reset, grant, expire, or remove credits. Reruns
   preserve saved records.
3. Deploy matching backend and rebuilt frontend together. Until setup is complete,
   the allocation section reports that it is awaiting setup.
4. Create a company policy first, then an allocation rule. Review hire dates and
   exclusions, preview the target year and post verified ready rows.
5. Inspect the saved batch and employee ledger. Run the existing ledger postflight
   to confirm journal totals still match balances. Deferred findings remain open.

Service-month credits are HR-reviewed top-ups; no scheduler posts them
automatically. Anniversary-based years, carryover, expiry, statutory event
entitlements, and the remaining request/approval settings are separate work.
The agent has not applied these migrations to the live database or posted
production employee credits.

## Validation

The disposable allocation suite covers daily, full, and completed-service-month
proration, incremental top-ups, request ceilings, existing-credit preservation,
exclusions, stale previews, atomic rollback, duplicate prevention, reversed
grants, tenant scope, future-year restrictions, and migration reruns. PHP syntax,
targeted frontend lint, and production builds are checked separately. These
checks do not claim live login or browser testing.