aeat.application.calculations._prorrata_regularizacion module

Advisory projection for the annual prorrata-general regularización (LIVA arts. 104-105).

Builds the projection and live source resolver for Modelo 303 casilla 44 (Regularización prorrata por porcentaje definitivo - Cuota) and the Modelo 390 annual regularización field when a taxpayer under prorrata general has exempt-without-right operations in the year and a provisional percentage was applied. The calculate path still keeps the advisory surface so missing provisional/current-year inputs never collapse into a silent zero.

This is a pure function over the two prorrata percentages and the year’s deductible input IVA, plus a resolver that consumes the governed prorrata register or a stamped prior-year settlement observation for the provisional percentage. The definitive percentage itself comes from the full-year volume rollup fed to compute_prorrata_definitiva_anual(); deriving it from a single quarter is a correctness defect (the silent-zero-base ADR).

The resolver reads the target ModeloRevision’s bindings to locate the casillas that carry the provisional/definitive percentages, and consumes a RegistrySnapshot to resolve those bindings’ legal and source refs.

See also

compute_regularizacion_prorrata_anual()

Pure LIVA art. 105.Cuatro computation consumed by this projection.

_prorrata_regularizacion_advisory

Calculate-path collector that calls this advisory projection from Modelo 303 values and prior-year observations.

_iva_ledger

Source of typed IVA ledger observations used for declared-volume divergence checks.

prorrata_register

Cross-period carry home for provisional and definitive prorrata percentages.

test_prorrata_regularizacion

Focused regressions for live-feed and ledger-divergence behavior.

CASILLA_REGULARIZACION_PRORRATA_DEFINITIVA: CasillaId

The Modelo 303 casilla the annual prorrata regularización feeds. Deducciones block, “Regularización prorrata por porcentaje definitivo - Cuota” (LIVA art. 105.Cuatro).

class ProrrataRegularizacionFeedProjection(**data)[source]

Bases: BaseModel

Structured proposed feeds for annual prorrata-general regularización.

These values feed the live source resolver and the operator-facing advisory for Modelo 303 casilla 44 and the Modelo 390 annual regularización field. Both come from the same RegularizacionProrrataResult, preserving the registry’s declared annual-volume authority for the definitive percentage.

See also

project_prorrata_regularizacion_feed()

Constructs this carrier from the pure annual regularización result.

Parameters:
result: RegularizacionProrrataResult
operaciones_sin_derecho_deduccion: Decimal
modelo_303_casilla_44_id: CasillaId
modelo_303_casilla_44_value: Decimal | None
modelo_390_regularizacion_anual_value: Decimal | None
class ProrrataDeclaredVolumeLedgerRollup(**data)[source]

Bases: BaseModel

Ledger-side annual volume rollup used only as a divergence advisory.

Declared annual volume casillas remain the filing authority. This projection records the currently classifiable ledger output-volume view so settlement can warn when it contradicts those declared values.

See also

build_prorrata_declared_volume_divergence_advisory()

Builds this rollup and the optional non-blocking diagnostic.

Parameters:

  • declared_volume_total (Decimal)

  • declared_volume_con_derecho (Decimal)

  • declared_volume_sin_derecho (Decimal)

  • ledger_volume_total (Decimal)

  • ledger_volume_con_derecho (Decimal)

  • ledger_volume_sin_derecho (Decimal)

  • included_ledger_ids (tuple[str, ...])

  • art_104_tres_excluded_ledger_ids (tuple[str, ...])

declared_volume_total: Decimal
declared_volume_con_derecho: Decimal
declared_volume_sin_derecho: Decimal
ledger_volume_total: Decimal
ledger_volume_con_derecho: Decimal
ledger_volume_sin_derecho: Decimal
included_ledger_ids: tuple[str, ...]
art_104_tres_excluded_ledger_ids: tuple[str, ...]

Ledger ids skipped from the rollup because they carry an operator-declared LIVA art. 104.Tres judgment exclusion (foreign PE, non-habitual inmobiliario/financiero). Recorded so the exclusion is auditable and the proposal is never a silent substitution of the declared volumes.

property diverges: bool
class ProrrataApplicabilityProjection(**data)[source]

Bases: BaseModel

Fail-closed-to-visible prorrata applicability evidence for one ejercicio.

Prorrata applies when the taxpayer has an active register entry or the ejercicio shows exempt-without-right operations through declared annual volumes or the ledger rollup. This projection is deliberately pure; later steps turn an applicable-but-unresolved state into calculate/verify diagnostics.

Parameters:
applies: bool
register_active: bool
declared_volume_sin_derecho: Decimal
ledger_volume_sin_derecho: Decimal
evidence_kinds: tuple[str, ...]
derive_prorrata_applicability(*, register_entries=(), declared_volume_total=None, declared_volume_con_derecho=None, ledger_rollup=None)[source]

Derive whether prorrata applies for an ejercicio.

The rule is intentionally fail-closed-to-visible: any active register entry (general or especial), any positive declared sin-derecho annual volume, or any positive ledger-projected sin-derecho annual volume means prorrata applies and later steps must not silently assume a full-deduction default.

Return type:

ProrrataApplicabilityProjection

Parameters:
build_prorrata_missing_provisional_advisory(*, applicability, provisional_resolution, ejercicio, first_ejercicio=False)[source]

Build the visible advisory for an applicable prorrata with no provisional percentage.

This is the per-period no-silent-under-declaration warning. It does not fabricate a percentage: an applicable-but-unresolved prorrata tells the operator to record the inicio-de-actividad percentage for a first ejercicio or seed/record the prior definitive percentage for subsequent ejercicios.

Return type:

CalculationSourceDiagnostic | None

Parameters:
class ProrrataInterruptedSeed(**data)[source]

Bases: BaseModel

The LIVA art. 105.Cinco resumption seed for an ejercicio after an interruption.

Carries the global definitive percentage over the aggregate of the last three active años naturales and the ProrrataProvisionalProvenance stamping it as the art. 105.Cinco three-year rule. When the register holds fewer than three active years the seed is unresolved (percentage is None) and the caller surfaces the insufficient-history advisory rather than assuming a percentage.

See also

build_interrumpida_tres_ultimos_seed()

Builds this seed and the optional insufficient-history diagnostic.

Parameters:
percentage: Decimal | None
provenance: ProrrataProvisionalProvenance | None
contributing_ejercicios: tuple[int, ...]
aggregate: ThreeActiveYearsAggregate | None
property resolved: bool

Whether the three-active-years rule resolved a percentage.

build_interrumpida_tres_ultimos_seed(register, *, ejercicio, sector_id=None)[source]

Seed a resumed ejercicio from the LIVA art. 105.Cinco three-active-years rule.

When the immediately prior year is interrupted, seed the resuming ejercicio from the GLOBAL definitive percentage over the AGGREGATE volumes of the last three active años naturales (skipping the interruption gap), computed via compute_prorrata_definitiva_anual() over the summed volumes - never the average of the three definitive percentages, never silently the single pre-interruption year. With fewer than three active years no percentage is assumed: a visible insufficient-history advisory is returned instead (no-silent-under-declaration).

See also

collect_last_three_active_years()

The register walk that aggregates the three active years’ volumes.

Return type:

tuple[ProrrataInterruptedSeed, CalculationSourceDiagnostic | None]

Parameters:
build_prorrata_declared_volume_divergence_advisory(*, declared_volume_total, declared_volume_con_derecho, ledger_observations, ejercicio_periods, regularizacion_year, art_104_tres_excluded_ledger_ids=())[source]

Compare declared annual prorrata volumes with the exclusion-filtered ledger rollup.

The rollup is deliberately advisory-only and remains a reconciliation pre-fill PROPOSAL, never a filed-volume authority: the operator-declared annual volume casillas keep the filing authority; this only surfaces a divergence. It applies the LIVA art. 104.Tres denominator exclusions on the ledger side before summing: the structural (cuotas), category-derived (art. 7 no-sujeta, art. 9.1.d autoconsumo) exclusions never enter because _prorrata_volume_side() already resolves them to neither term, and the operator-declared judgment exclusions (foreign PE, non-habitual inmobiliario/financiero) are skipped here by ledger id via the art_104_tres_excluded_ledger_ids argument (typically art_104_tres_excluded_ledger_ids): observations with those ids are removed from both terms of the ledger-side ratio and recorded on the rollup so the exclusion is auditable, never silent. The bienes-de-inversión exclusion (art. 104.Tres 3.º) is owned by the bienes-inversión register and is not applied here.

See also

IvaLedgerObservation

Typed ledger observation stream classified into con-derecho and sin-derecho output volumes.

Return type:

tuple[ProrrataDeclaredVolumeLedgerRollup, CalculationSourceDiagnostic | None]

Parameters:
project_prorrata_regularizacion_feed(*, cuotas_soportadas_deducibles, prorrata_provisional_pct, prorrata_definitiva_pct, operaciones_sin_derecho_deduccion)[source]

Project the annual regularización onto the M303 and M390 filing targets.

prorrata_definitiva_pct is supplied by the registry-computed annual volume casillas. This helper deliberately does not recompute that percentage; it turns the pure art-105 result into the two filing values used by the live resolver and the advisory surface.

See also

ProrrataRegularizacionFeedProjection

Structured carrier for the two proposed filing values.

Return type:

ProrrataRegularizacionFeedProjection

Parameters:

  • cuotas_soportadas_deducibles (Decimal)

  • prorrata_provisional_pct (Decimal)

  • prorrata_definitiva_pct (Decimal)

  • operaciones_sin_derecho_deduccion (Decimal)

class ProrrataRegularizacionSourceResolver(*, current_year_values=None, missing_current_year_casilla_ids=(), unresolved_current_year_casilla_ids=(), prorrata_register_repository=None, observation_repository=None, registry_snapshot=None)[source]

Bases: object

Resolve annual prorrata-general regularisation bindings from governed carries.

Parameters:
resolver_id
owned_sources: tuple[BindingSourceKind, ...]
resolve(context)[source]
Return type:

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

build_prorrata_regularizacion_advisory(*, cuotas_soportadas_deducibles, prorrata_provisional_pct, prorrata_definitiva_pct, operaciones_sin_derecho_deduccion, regularizacion_year)[source]

Compute the annual regularización and build the fallback advisory.

Returns the pure RegularizacionProrrataResult plus a non-blocking CalculationSourceDiagnostic when the taxpayer has exempt-without-right operations in the year (operaciones_sin_derecho_ deduccion > 0 — prorrata applies) and the definitive percentage differs from the provisional one applied across the quarters (a regularización is due). In that case a taxpayer who leaves casilla 44 blank is alerted rather than silently under- or over-declaring. When prorrata does not apply, or the two percentages coincide, the diagnostic is None (nothing to regularise, no noise).

The diagnostic message names the provisional and definitive percentages, the direction (deducción complementaria vs ingreso), and the proposed casilla-44 value.

Parameters:

  • cuotas_soportadas_deducibles (Decimal) – The year’s total deductible input IVA (LIVA art. 105.Seis).

  • prorrata_provisional_pct (Decimal) – Provisional deduction percentage applied during the year (LIVA art. 105.Uno — the prior-year definitive).

  • prorrata_definitiva_pct (Decimal) – Definitive deduction percentage for the year (LIVA art. 104, computed from full-year volumes).

  • operaciones_sin_derecho_deduccion (Decimal) – The year’s exempt-without-right operation volume. When zero, prorrata does not apply and no regularización is proposed.

  • regularizacion_year (int) – The year being calculated (for the message).

Return type:

tuple[RegularizacionProrrataResult, CalculationSourceDiagnostic | None]

Returns:

(result, diagnostic) where result is the RegularizacionProrrataResult; the diagnostic is None when there is nothing to regularise.

build_prorrata_especial_mandatory_advisory(*, deduction_under_general, deduction_under_especial, ejercicio)[source]

Build the LIVA art. 103.Dos.2 +10% mandatory-especial settlement advisory.

At settlement (4T / 0A), once the ejercicio’s deducción computed under the general regime and under the especial regime are both known, art. 103.Dos.2 makes prorrata especial OBLIGATORY when the general-regime deduction exceeds the especial-regime deduction by ten percent or more (is_especial_mandatory()). This surfaces that obligation as a NON-BLOCKING warning Notice so the operator elects and records especial before filing; it NEVER refuses the in-progress filing (the especial election is a filed taxpayer decision and the classification data may still be incomplete). Both compared totals ride on Notice.context alongside the ejercicio and the binding legal reference.

Returns None when especial is not obligatory (no noise); the two amounts must be non-negative (is_especial_mandatory() refuses negatives).

Parameters:

  • deduction_under_general (Decimal) – The ejercicio’s total deducible IVA under the prorrata general regime (single whole-entity percentage).

  • deduction_under_especial (Decimal) – The ejercicio’s total deducible IVA under the prorrata especial regime (per-input art. 106 routing).

  • ejercicio (int) – The filing year being settled (for the message and context).

Return type:

Notice | None