cadrumo.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 CalculationObservationRepositoryProtocol reads, IvaWalletDecisionRepositoryProtocol 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: ClassVar[str]
owned_sources: ClassVar[tuple[BindingSourceKind, ...]]
binding_id
resolve(context)[source]

Resolve the Modelo 303 IVA wallet decision binding for context.

Return type:

CalculationSourceResolution

Returns:

An empty resolution when the modelo is not Modelo 303 or no decision was supplied, otherwise the resolved CalculationSourceResolution carrying the selected amount and its provenance.

Raises:

IvaCompensationReconciliationInputError – When the decision does not target this filing year and period, blocks the calculation, or carries no selected amount.

Parameters:

context (CalculationSourceContext)

reconcile_modelo_303_iva_compensation(snapshot, *, taxpayer_nif, wallet, repository, decision_repository, override=None, decided_at=None, max_wallet_age_days=31, treat_absent_recurrence_as_first_period=False, local_evidence_found_but_unusable=False, local_recurrence, prefill_report, persist=True, operation)[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 IvaWalletDecisionRepositoryProtocol 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 (CalculationObservationRepositoryProtocol) – Required CalculationObservationRepositoryProtocol used to read prior local recurrence.

  • decision_repository (IvaWalletDecisionRepositoryProtocol) – Required IvaWalletDecisionRepositoryProtocol used to persist the resulting wallet authority. When persistence is enabled, it must use the same encrypted storage backend as repository.

  • 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.

  • local_evidence_found_but_unusable (bool) – Whether the caller FOUND a prior local record and could not interpret it as prior-compensation evidence. Only the caller knows this: an absent amount looks the same here whether nothing was stored or something was and could not be read. It changes no outcome, only what the no-authority decision says, so an operator is not told nothing exists while their own prior record sits in the store.

  • local_recurrence (LocalIvaCompensationRecurrence | None) – Required caller-resolved canonical recurrence, or explicit None when the caller found no admissible recurrence.

  • prefill_report (BindingPrefillReport) – Required report from the same recurrence resolution. Reconciliation never performs a second repository fallback.

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

  • operation (PinnedAuthorityOperation) – Caller-owned generation-pinned authority operation used to resolve first-period governed facts.

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.