ccnl_engine¶

The run: its month, year and kind.

Date the run is paid. Selects the tax year (:class:~ccnl_engine.calendar.tax_year.rules.TaxYearPolicy).

Contract, level and worker facts.

The employer. Required: its headcount selects the INPS rate tier.

Facts of the run. Defaults to a run with no event and no surtax jurisdiction.

Prior-year income and waivers. Defaults to unknown income and no waiver.

Income of the tax year beyond this employment, which the family deductions add to the employment income of the year to get the reddito complessivo, and the INPS base of the other employments of the year. None means not known: with a dependent that gives right to a deduction, or INPS rules with a massimale or a 1% threshold and no base of other employments in opening_state, the result is not payable.

State entering the run, with the history of the employment. The default :meth:~ccnl_engine.balance.models.PeriodState.zero is the fact only for the first run of an employment whose employment_period starts in the run month; pass the closing_state of the previous run within a tax year, close_tax_year() of the last run of the previous year, or imported balances. A state that misses the history gives a missing_fact opening_state blocker.

Payments of the same tax year still planned after this one, in payment order, when they differ from the CCNL standard calendar. () makes this payment the conguaglio: pass it on the last payment of a tax year whose December is paid after 12 January. None (the default) projects the standard runs that follow this run and are not yet paid.

When a field is not of its type, a regular run falls outside the employment, the payment precedes the run month, or opening_state belongs to another tax year.

Hours worked and paid in the run that are subject to INPS contributions. Required for domestic CCNLs.

Ordinary hours actually worked in the month, sickness, ferie, permits, festività and other paid absences left out: the hours a CCNL with hourly_pay pays its worker (the operai of the building CCNLs) and the base of the Prevedi contractual contribution of an operaio. None is unknown: an operaio then has a missing_fact blocker. An AbsenceEvent of a worker paid by the hour is rejected: its hours are already left out of them.

Variable work events of the run (overtime, absences, bonuses, supplements), each one of the :data:~ccnl_engine.event.types.WorkEvent types. A list is accepted and stored as a tuple.

ISO 3166-2:IT region code for the regional surtax, e.g. "IT-45", "IT-BZ" / "IT-TN" for the autonomous provinces. None is unknown: when the employer withholds, a residence_unknown decision and a requirement_unresolved blocker on addizionale_regionale.

Belfiore code for the municipal surtax, e.g. "F257". None is unknown: when the employer withholds, a residence_unknown decision and a requirement_unresolved blocker on addizionale_comunale.

Dependents for the Art. 12 TUIR deductions. None is unknown: when the employer withholds, a requirement_unresolved blocker on family_deductions; FamilyComposition() states that there is no dependant. Its children also select the fringe-benefit threshold: the higher one when a child is within the own-income limit of art. 12 c. 2 TUIR (L. 207/2024 art. 1 c. 390).

When a field is not of its type, an event is not a work event, or a surtax code is malformed.

Classification of the run type:

• RunKind.REGULAR — ordinary monthly salary period.
• RunKind.THIRTEENTH — tredicesima mensilità.
• RunKind.FOURTEENTH — quattordicesima mensilità.
• RunKind.ADJUSTMENT — conguaglio correction run.
• RunKind.TERMINATION — cessazione run including TFR settlement.

Calendar month (1-12) of the run.

Year of the run month. The tax year follows from the payment date (:class:~ccnl_engine.calendar.tax_year.rules.TaxYearPolicy) and can be the next year when the run is paid late.

Number of the run among the runs of its kind and month, from 1. Above 1 only for a second or later adjustment run of the month (:meth:adjustment).

Unique, deterministic identifier derived from year, month, kind and sequence, e.g. "2026-01-regular" or "2026-12-adjustment-2". Computed automatically; do not pass to the constructor.

Knowledge-bundle CCNL filename, e.g. "metalmeccanico-federmeccanica.json": lower-case letters, digits and hyphens, then .json. A name the bundle does not hold raises :class:~ccnl_engine.errors.UnknownCcnlError when the run loads it.

Contractual level code, e.g. "C3".

:class:Permanent, :class:FixedTerm or :class:Apprentice, always stated: it selects the NASpI surcharge of a fixed-term contract and the art. 13 TUIR deduction minimum.

Worker category; its string value (e.g. "operaio") is accepted and normalized. None takes the category fixed by the level, if any. The calculation raises when the category differs from the one the level fixes, or when it is None and seniority increments for the level differ by category.

Start and optional end of the employment. None when not tracked: a year then computes every run of the calendar with full ratei.

Contracted weekly hours. Required for domestic CCNLs to select the INPS bracket; below full_time_weekly_hours it scales the pay for part time.

Full-time weekly hours of the contract. weekly_hours must not exceed it.

Recognised seniority, aged by the engine to each run. None means not known: a run whose level pays seniority increments or service-gated allowances then has a missing_fact blocker, and its amounts leave them out.

Role codes that unlock role-specific contractual allowances, each a non-blank string. A set is accepted and stored as a frozenset; an empty set states that the worker holds no role. None means not known: a run whose level has an allowance restricted to a role then has a missing_fact blocker, and its amounts leave the allowance out.

First enrolment in a mandatory pension scheme and contributory option, from which the engine derives whether the IVS massimale applies. None means not known: a run whose INPS base crosses the massimale then has an undetermined contribution and a missing_fact blocker.

Private or public sector of the employment, for the regimes restricted to one sector. None means not known: those regimes are then unknown and the result provisional. It is not derived from the CCNL: a public employer may apply a private CCNL.

Enrolment in a complementary pension fund of the CCNL, or :class:~ccnl_engine.pension_fund.inputs.NoPensionFund to state that the worker is not enrolled: no fund contribution is computed, and on a CCNL that has funds the pension_fund_contribution capability records the reason not_enrolled. None means not known: on every CCNL but domestic work the contributions are undetermined and the run has a missing_fact blocker.

TFR fund at 31 December of the year before the run, the base of the revaluation at 31 December (art. 2120 c. 4 c.c.). None means not known: the December run then has a missing_fact blocker, unless the employment starts in the year of the run (no fund to revalue).

Whether the TFR not paid to a pension fund is paid to the Fondo Tesoreria INPS (L. 296/2006 art. 1 c. 756): the employer is obliged by its size and the worker is not excluded (DM 30 gennaio 2007 art. 1 cc. 5-8). None means not known: a run that accrues TFR in the company then has a missing_fact blocker. Domestic work and the public administrations are outside the Fondo: True there raises InvalidInputError, None and False keep the TFR in the company.

Annual Elemento di Raccordo Contrattuale of the CCNL grafici editoriali (renewal of 19 January 2021), frozen in December 2020; zero when the worker has none. It is paid with the tredicesima, by its months, and sets the Byblos employer rate (1.4% with one, 1.9% without). None means not known, zero for an employment that started after December 2020: an enrolled run, or a run paying the tredicesima, on that CCNL has a missing_fact blocker.

End-of-service regime of a public employee (TFS, TFR at INPS or TFR at the employer), which sets the contributions to INPS Gestione Dipendenti Pubblici and whether the run accrues the TFR. None means not known: a run on a CCNL of the public administrations has a missing_fact blocker.

When a field is not of its type, a role is not a non-blank string, weekly_hours exceeds full_time_weekly_hours, or category or sector names no known value.

Employer headcount, used to select the INPS contribution tier. Required: no size is assumed.

Activity of the employer, for the regimes that exclude some activities. None means not known: the night, holiday and shift substitute tax (L. 199/2025 art. 1 c. 11) excludes the activities of c. 18, so its eligibility is then unknown.

Whether a public employer enrols its staff in the Assicurazione Sociale Vita (ex ENPDEP): every "ente dotato di personalità giuridica di diritto pubblico" except the State, the Province, the Comuni and the enti di assistenza e beneficenza (INPS circ. 104/2014). None takes the value the CCNL fixes; when it fixes none, a run of the public administrations has a missing_fact blocker.

Whether an employer of the fondo di integrazione salariale with on average up to five employees has its rate cut by 40% for not having applied for the assegno di integrazione salariale in the last twenty-four months (D.Lgs. 148/2015 art. 29 c. 8-bis). None means not known: a run of such an employer has a missing_fact blocker and is charged the full rate.

Whether a craft firm with more than fifteen employees works in the indotto of a firm with the prevailing management influence, owing the CIGS contribution (D.Lgs. 148/2015 art. 20 c. 1 lett. b, art. 23 c. 1). None means not known: a run of such an employer has a missing_fact issue and is charged without it.

Whether a provincial pay element of the CCNL (a terzo elemento provinciale) is in force where the worker works, replacing the national element the CCNL pays only in its absence (Commercio Art. 215). None means not known: a level with such a national element leaves it out and has a missing_fact blocker.

Zone of the land of an agricultural employer, which cuts its INPS contributions by 68% in a zona svantaggiata and 75% in a zona particolarmente svantaggiata (INPS circ. 43/2026 par. 7). None means not known: an agricultural run is charged the full rates and has a missing_fact blocker.

When headcount is not a :class:Headcount, activity is not an :class:EmployerActivity value, agricultural_zone not an :class:AgriculturalZone value or public_life_insurance, fis_reduction or provincial_pay_element is not a bool.

Number of employees, >= 1.

When value is not an int or is below 1.

The competence year of the runs.

Contract, level and worker facts.

The employer. Required: its headcount selects the INPS rate tier.

Prior-year income and waivers. Defaults to unknown income and no waiver.

Income beyond this employment of the tax year of the runs, read by the family deductions; runs paid in another tax year ignore it. Its INPS base of other employments counts toward the massimale of the runs of the same competence year. None means not known.

Facts per run, keyed by run id ("2026-12-thirteenth", any run kind) or by month number (1-12, the regular run of the month). :attr:facts_by_run holds them keyed by run id. The plan keeps a read-only copy: changing the mapping passed in, or mutating this one, cannot change the runs it calculates. An entry replaces :attr:default_facts for its run: repeat the jurisdiction and family in it, e.g. with dataclasses.replace(default_facts, events=...).

Facts of every run without an entry in :attr:periods, extra-month runs included. Must carry no event.

A calendar that replaces the CCNL standard one, with its reason. None runs the standard calendar. An override that drops or lowers an extra month the CCNL grants, or does not match its reason, raises when the year is calculated.

Day of the run month on which a run is paid, 1-28, unless :attr:payment_dates names its date or the CCNL fixes the day of its quattordicesima (Commercio: 1 July) and the plan has no :attr:calendar_override.

Payment date per run, keyed like :attr:periods: {12: date(2027, 1, 13)} pays the December salary on 13 January 2027; an employer that pays in arrears names every month. A date before the first day of the run month is rejected.

State the first run opens with, read by calculate_competence_year. None is the zero state, the fact only for an employment whose stated start falls in :attr:year; otherwise the runs have a missing_fact opening_state blocker. Pass close_tax_year() of the previous tax year, imported balances, or the next_opening_state of the previous competence year when its December was paid in this tax year. A state that already closed some runs of :attr:year with the same payment resumes after them. Leave it None in a TaxYearPlan, which carries its own.

When a field is not of its type, a key of :attr:periods or :attr:payment_dates is not a month or a run id of :attr:year, two keys name the same run, :attr:default_facts carries events, a payment date precedes its run month, or payment_day is outside 1-28.

The tax year.

Plans of the competence years paid in the tax year, at most one per year, none after :attr:tax_year: usually the year before (for a December paid in January) and the tax year itself. Their own opening_state must be None.

State the first payment opens with: None (the zero state) only for an employment whose stated start falls in the plans, else the payments have a missing_fact opening_state blocker; close_tax_year() of the previous tax year, imported balances, or a state of :attr:tax_year that already closed some of the payments; those are not computed again (resume after a retry).

Income of :attr:tax_year beyond this employment and the INPS base of the other employments, read by every payment in place of the current_year of the competence years. None keeps theirs.

When a field is not of its type, there is no competence year, two plans share a year, a plan is of a year after :attr:tax_year or carries an opening state, or :attr:current_year is of another tax year.

The competence period, identical to the request.

Payment date, identical to the request.

Contractual gross entitlement for this period (sum of CASH_EARNINGS ledger entries). This is the theoretical wage the worker is entitled to before absence deductions.

Net pay for this period only.

Employer cost net of unpaid absences: period_gross - unpaid_absence_deduction + employer_contributions + bilateral_fund_employer + tfr_accrual + non_cash_benefits + pension_fund_employer + pension_fund_tfr + tfr_treasury_fund. It leaves out the INAIL premium, which rests on the tariff rate of the employer, and IRAP. It is complete within that perimeter only when :attr:is_employer_cost_complete: an amount the CCNL owes for every worker that the engine does not compute (a health fund) leaves it short.

Sum of EMPLOYEE_DEDUCTIONS ledger entries. Represents wages not paid due to unpaid absences or sickness. Zero when no absences are present.

State after closing this period: the tax year state and the obligations. Pass as opening_state to the next run of the same tax year, or to :func:~ccnl_engine.year.tax_year.closing.rules.close_tax_year after the last run of the year.

All pay items produced for this period.

All ledger entries posted for this period.

Per-component INPS breakdown for audit and compliance tracing.

Per-axis fringe/welfare benefit breakdown for audit and cost-centre reporting.

Gaps between the capability catalog and what the run executed, with the provenance of the rules each capability read and the values the caller supplied.

Conditions that lower the reliability of this result, in the order they were raised. Empty when every capability decided from known rules and facts.

What the capabilities that record a decision decided in this run, e.g. the eligibility of a pay item for a preferential tax regime, in the order they were taken.

Assurance of the rulesets the run read: the CCNL, and each tax, INPS and surtax ruleset a payable rule came from, with identity, hash, readiness and confidence.

Payability policy of the engine that produced the result; operational adds a blocker for every ruleset short of production.

Model limitations that concern the run (see :class:~ccnl_engine.limitation.models.ModelLimitation); an open one with a monetary impact blocks the amounts.

The competence year.

The calendar the year ran on: the CCNL standard calendar, or the accepted override.

The override that replaced the standard calendar, with its reason and note, or None when the standard applied.

The tax year.

Every payment of the tax year in payment order: those the opening state had already closed, then those computed.