cadrumo.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 (a silent zero base).

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.

application.calculations.tests.test_prorrata_regularizacion

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

class ProrrataRegularizacionFeedProjection(**data)[source]

Bases: BaseModel

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

The proposed value feeds the live source resolver and the operator-facing advisory. The selected registry revision supplies the output destinations; this carrier intentionally contains no filing-model or casilla facts.

See also

project_prorrata_regularizacion_feed()

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

Parameters:

data (Any)

result: RegularizacionProrrataResult
operaciones_sin_derecho_deduccion: Decimal
proposed_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.

Parameters:

data (Any)

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.

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:

data (Any)

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, revision, 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.

Core types: ModeloRevision.

Return type:

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 selected registry 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 result into one generic proposed value. The live resolver fans that value out only to destinations declared by selected binding rows.

See also

ProrrataRegularizacionFeedProjection

Structured carrier for the proposed registry value.

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, observation_repository, operation, registry_snapshot=None)[source]

Bases: object

Resolve annual prorrata-general regularisation bindings from governed carries.

Parameters:
resolver_id: ClassVar[str]
owned_sources: ClassVar[tuple[BindingSourceKind, ...]]
resolve(context)[source]

Resolve the annual prorrata regularisation casilla for the active revision.

Loads the compiled revision (reusing registry_snapshot when set) to discover the declared prorrata binding ids, then delegates to the governed carry lookup to produce the bound value or an explicit missing/unresolved diagnostic.

Return type:

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

buildprorrata_regularizacion_advisory(*, cuotas_soportadas_deducibles, prorrata_provisional_pct, prorrata_definitiva_pct, operaciones_sin_derecho_deduccion, regularizacion_year, revision)[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).

  • revision (ModeloRevision) – The selected Modelo 303 revision whose bindings declare the regularisation target casilla.

Return type:

tuple[RegularizacionProrrataResult, CalculationSourceDiagnostic | None]

Returns:

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

Core types: ModeloRevision.

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

Build the LIVA art. 103.Dos.2.º 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 the margin in force for that ejercicio — ten percent or more from 2015, more than twenty percent before it (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).

  • parameters (ProrrataEspecialMandatoryParameters) – The registry-resolved LIVA art-103.Dos.2 margin and its comparison direction for that ejercicio.

  • operation (PinnedAuthorityOperation) – Caller-owned generation-pinned authority operation used to resolve the advisory’s legal reference.

Return type:

Notice | None