aeat.application.modelo._iva_wallet_gate module

Modelo IVA wallet gate for calculation and filing lifecycle checks.

Modelo 303 prior-compensation belongs to the IVA wallet authority, not to the generic previous-filing source mesh. This module uses the calculation RegistrySnapshot and ModeloRevision to route the wallet decision into the prior-compensation binding, then checks a persisted IvaCompensationReconciliationDecision against the exported or filed CalculationRevision.

The gate is deliberately repository-backed: transient wallet decisions cannot feed the Modelo 303 engine unless the same decision is already present in IvaWalletDecisionRepository for the work-unit taxpayer and period. Calculation, verification, internal filing, and export all replay this authority instead of trusting a caller-provided binding value for casilla 110. Blocked, missing, stale, target-mismatched, or amount-mismatched decisions raise ModeloIvaWalletReconciliationBlockedError before a revision, filing record, or fichero-BOE artefact can be persisted.

The only lazy path is local-authority derivation for a bucket-scoped WorkUnit: it can persist a non-blocking local recurrence decision, and a first_period_zero decision is accepted only when profile activity-start evidence and the RegistrySnapshot prove every prior Modelo 303 compensation dependency is pre-activity.

See also

reconcile_modelo_303_iva_compensation():

Builds and persists the reconciliation decision consumed here.

IvaWalletDecisionSourceResolver:

Projects a non-blocking decision into calculation binding values.

_require_cross_period_clean_state():

Treats matching IVA-wallet authority as the Modelo 303 compensation gate.

export_modelo_revision():

Replays this gate before writing a Modelo 303 export artefact.

exception ModeloIvaWalletReconciliationBlockedError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloError

Raised when Modelo 303 calculation is blocked by IVA wallet reconciliation.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
ModeloIvaWalletReconciliationBlocked

alias of ModeloIvaWalletReconciliationBlockedError

resolve_iva_compensation_decision_for_calculation(work_unit, *, snapshot, supplied_decision, repository, work_unit_repository=None, calculation_repository=None, binding_values, backend_binding_values, casilla_inputs, backend_casilla_inputs)[source]

Resolve the Modelo 303 IVA wallet decision that may feed calculation bindings.

The WorkUnit fixes the bucket, taxpayer profile lookup, target period, and registry revision; the RegistrySnapshot is passed to the lazy reconciliation path when no caller-supplied or persisted wallet decision exists. A supplied decision must match the persisted IvaCompensationReconciliationDecision. If the caller supplied a prior-compensation binding or casilla without a decision, the function tries only the local-authority zero path and otherwise returns None so calculation surfaces the seed/reconcile guidance instead of silently trusting the value.

Return type:

object | None

Parameters:
apply_iva_compensation_decision_binding(modelo, filing_year, period, *, bucket_id, revision, taxpayer_nif=None, casilla_inputs=None, backend_casilla_inputs=None, caller_binding_values, backend_binding_values, decision)[source]

Apply a non-blocking IVA wallet decision to Modelo 303 binding values.

The ModeloRevision defines the binding channel; the decision amount is written only after target period and taxpayer identity checks pass. Caller and backend inputs for the same binding or casilla must either match the selected decision amount or are refused as conflicts. The effective value is then produced through IvaWalletDecisionSourceResolver, so the calculation source mesh records the IVA-wallet provenance instead of a generic previous_filing source.

Return type:

None

Parameters:
require_persisted_iva_compensation_decision_for_work_unit(work_unit, *, supplied_decision, snapshot=None, repository=None)[source]

Require a supplied Modelo 303 wallet decision to match the persisted decision.

The optional RegistrySnapshot grounds first-period-zero decisions; when omitted, the function resolves the snapshot from the supplied WorkUnit. This check prevents a transient or stale IvaCompensationReconciliationDecision from feeding calculation values unless the repository contains the same authority record.

Return type:

object

Parameters:
load_persisted_iva_compensation_decision_for_work_unit(work_unit, *, repository=None)[source]

Load the persisted IVA compensation decision for a WorkUnit.

Return type:

IvaCompensationReconciliationDecision | None

Returns:

The persisted IvaCompensationReconciliationDecision for Modelo 303 work units, or None when the work unit or bucket has no wallet authority record.

Parameters:
caller_supplied_prior_compensation_value(*, binding_values, backend_binding_values, casilla_inputs, backend_casilla_inputs)[source]

Return whether a Modelo 303 prior-compensation value was explicitly supplied.

The lazy local reconciliation must not fire when the operator or a backend resolver explicitly asserts the prior-compensation binding/casilla. That value needs reconciliation against a real wallet/seed decision, and the seed-verb guidance must surface.

Return type:

bool

Parameters:
lazily_reconcile_local_iva_compensation_for_work_unit(work_unit, *, snapshot, repository=None, work_unit_repository=None, calculation_repository=None, persist=True)[source]

Auto-derive and persist the local-authority Modelo 303 compensation decision.

Calculate’s prior-compensation gate requires a persisted IvaCompensationReconciliationDecision. In the seed-only local authority case, the local Modelo 303 recurrence is the authority, so derive and persist the decision here instead of refusing calculation.

The RegistrySnapshot supplies the Modelo 303 revision context for the reconciliation service. Missing local recurrence is treated as first_period_zero only when the work unit’s profile activity-start date scopes every Modelo 303 compensation dependency out as pre-activity; otherwise the reconciliation remains a blocking missing-authority state.

Return type:

IvaCompensationReconciliationDecision | None

Parameters:
require_persisted_iva_compensation_decision_matches_revision(work_unit, revision, *, repository=None)[source]

Return the IVA compensation decision when it matches the revision.

The check reads the supplied CalculationRevision and blocks verification, internal filing, or export when its Modelo 303 prior-compensation amount differs from the persisted wallet decision, when the decision targets another period, or when the decision is blocked/missing. Non-Modelo 303 work units return None because the IVA wallet authority owns only Modelo 303 prior compensation.

Return type:

IvaCompensationReconciliationDecision | None

Returns:

The matching IvaCompensationReconciliationDecision for Modelo 303, or None for non-Modelo 303 work units.

Parameters:
revision_iva_compensation_amount(revision)[source]

Return the Modelo 303 prior-compensation amount carried by a revision.

Reads the CalculationRevision casilla values first, then binding overrides, matching the persisted calculation payload.

Return type:

Decimal | None

Parameters:

revision (CalculationRevision)

iva_wallet_blocked_message(decision)[source]

Render a localized IVA wallet blocked message from a decision-like object.

Return type:

str

Parameters:

decision (_IvaWalletBlockedDecision)

iva_wallet_override_suggestion(decision)[source]

Return the explicit taxpayer-override command for a blocked wallet decision.

Return type:

str

Parameters:

decision (object)

taxpayer_nif_for_bucket(bucket_id)[source]

Return the profile tax id for a bucket, or None when absent.

Return type:

str | None

Parameters:

bucket_id (str)