aeat.application.calculations._iva_wallet_reconciliation module

IVA compensation wallet reconciliation orchestration.

The live AEAT wallet is external state. Local Modelo 303 recurrence is internal reconstruction. This module is the application boundary that turns those evidence sources, plus an explicit taxpayer override when present, into the effective binding decision consumed by Modelo 303 calculation.

The pure decision logic (reconcile_iva_compensation_wallet() and its wallet/recurrence predicates) lives in _reconciliation; it consumes structural ports such as IvaCompensationWalletObservationProtocol and LocalIvaCompensationRecurrenceProtocol so the domain never imports the Sede adapter. This module orchestrates CalculationObservationRepository reads, IvaWalletDecisionRepository persistence, and source-mesh resolution around that pure decision.

Binding resolution reads its active revision through a RegistrySnapshot supplied via the source mesh context.

See also

extract_modelo_303_local_iva_compensation_recurrence()

Reconstructs the local Modelo 303 recurrence compared with wallet evidence.

CalculationSourceResolution

The source-mesh envelope produced by IvaWalletDecisionSourceResolver.

class IvaCompensationReconciliationReport(**data)[source]

Bases: BaseModel

Application-level reconciliation result for one Modelo 303 target.

Carries the domain IvaCompensationReconciliationDecision plus the BindingPrefillReport used to reconstruct the local recurrence side of the comparison.

Parameters:
decision: IvaCompensationReconciliationDecision
prefill_report: BindingPrefillReport
class IvaWalletDecisionSourceResolver(decision)[source]

Bases: object

Source-mesh adapter for persisted Modelo 303 IVA wallet decisions.

Owns iva_wallet_decision and materialises the modelo-303-compensacion-pendiente-anteriores binding from a persisted IvaCompensationReconciliationDecision. The returned CalculationSourceResolution carries the selected amount plus provenance for every authority source that participated in the wallet/filed-history/local-recurrence decision.

Parameters:

decision (IvaCompensationReconciliationDecision | None)

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

reconcile_modelo_303_iva_compensation(snapshot, *, taxpayer_nif, wallet, repository=None, decision_repository=None, override=None, decided_at=None, max_wallet_age_days=31, treat_absent_recurrence_as_first_period=False, fallback_local_recurrence=None, persist=True)[source]

Resolve, compare, and optionally persist the Modelo 303 IVA wallet decision.

The function validates wallet evidence against the target RegistrySnapshot, reconstructs local recurrence through extract_modelo_303_local_iva_compensation_recurrence(), delegates authority selection to reconcile_iva_compensation_wallet(), and persists the resulting IvaCompensationReconciliationDecision through IvaWalletDecisionRepository when persist is true.

Parameters:

  • snapshot (RegistrySnapshot) – The RegistrySnapshot identifying the Modelo 303 target revision.

  • taxpayer_nif (str) – Taxpayer identifier expected to match live wallet evidence.

  • wallet (IvaCompensationWalletObservationProtocol | None) – Live AEAT wallet observation to reconcile, when available.

  • repository (CalculationObservationRepository | None) – Optional CalculationObservationRepository used to read prior local recurrence.

  • decision_repository (IvaWalletDecisionRepository | None) – Optional IvaWalletDecisionRepository used to persist the resulting wallet authority.

  • override (IvaCompensationOverride | None) – Optional IvaCompensationOverride evidence when the operator has resolved a divergence.

  • decided_at (datetime | None) – Decision timestamp override for deterministic replay and tests.

  • max_wallet_age_days (int) – Maximum accepted age for live wallet evidence.

  • treat_absent_recurrence_as_first_period (bool) – When True and there is no live wallet and no prior local recurrence, treat the target as the taxpayer’s FIRST IVA period: iva.compensacion-pendiente-periodos-anteriores is zero per LIVA art. 99.5 (no prior compensation balance can exist), yielding the non-blocking first_period_zero decision instead of the missing block. The caller asserts first-period status (e.g. the calculate path verifies no prior 303 compensation history exists). It NEVER fabricates a non-zero balance: a present recurrence still flows through normally.

  • fallback_local_recurrence (LocalIvaCompensationRecurrence | None) – Optional local recurrence evidence supplied by the caller when the repository-backed previous-filing/history pass has no row, for example a current prior-period calculated revision.

  • persist (bool) – Whether to store the resulting decision for later calculation replay.

Return type:

IvaCompensationReconciliationReport

The local side is not recomputed here. It is read through the same previous-filing binding resolver used by the calculation chain.

Returns an IvaCompensationReconciliationReport.

See also

IvaWalletDecisionSourceResolver

Converts a persisted non-blocking decision into the Modelo 303 iva_wallet_decision source value.