aeat.application.modelo._iva_wallet_seed module

Application facade for Modelo 303 IVA wallet seed and override operations.

This module resolves the active bucket to a taxpayer NIF, validates the operator-supplied amount, and then delegates the persistence write to the calculation layer. Seed and correction flows write IvaCompensationPeriodState records through seed_iva_compensation_period / correct_iva_compensation_period; override flows persist an IvaCompensationReconciliationDecision through reconcile_modelo_303_iva_compensation. Every mutation appends a typed bucket event via BucketEventHistoryRepository.

The facade is intentionally above the pure writers. It can scan work units and calculation revisions before changing an opening carry-forward basis, so correct_iva_compensation_period_for_bucket() and record_iva_compensation_override_for_bucket() refuse changes once a sealed Modelo 303 revision has consumed that basis.

See also

aeat.application.calculations._iva_compensation_history Single-writer seed and correction primitives for local IVA compensation history. aeat.application.calculations._iva_wallet_reconciliation Reconciliation service that turns wallet/local/override evidence into a persisted Modelo 303 prior-compensation decision. aeat.application.modelo._iva_wallet_gate Calculation/export gate that replays the persisted wallet decision before a Modelo 303 revision is allowed to use the binding.

exception ModeloIvaWalletSeedError(*, translated_message, context=None)[source]

Bases: ModeloError

Base class for Modelo IVA wallet seed, correction, and override errors.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletSeedNoTaxpayerError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when the selected bucket cannot provide a taxpayer NIF.

The seed facade uses aeat.application.modelo._iva_wallet_gate.taxpayer_nif_for_bucket() so the same bucket/profile identity authority feeds seed, correction, override, and persisted-decision replay paths.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletSeedNegativeAmountError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when an operator supplies a negative seed, correction, or override amount.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletCorrectionNoRecordError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when a correction targets a period that has no seeded record yet.

Correction re-writes an existing opening balance; an absent period is a seed, not a correction. The refusal surfaces the seed-first guidance so the operator runs iva-wallet seed before iva-wallet correct.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletCorrectionSealedError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when correcting a seed that an already-filed Modelo 303 consumed.

A sealed (VERIFICADO_COMPLETO / PRESENTADO / PRESENTADO_SUPERSEDIDO) Modelo 303 revision at or after the seeded period carries the seeded compensation forward as its compensación pendiente de periodos anteriores. Re-writing that basis would silently change the input basis of a return the operator has already filed at sede — the same filed-immutability risk the ledger restore guard enforces — so the correction is refused with the offending revision named.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletOverrideSealedError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when an override targets a period a filed Modelo 303 already consumed.

A sealed (VERIFICADO_COMPLETO / PRESENTADO / PRESENTADO_SUPERSEDIDO) Modelo 303 revision at or after the period carries that period’s compensación forward as its compensación pendiente de periodos anteriores. Recording an override would silently change the basis of a return the operator has already filed — the same filed-immutability risk the correction guard and the ledger restore guard enforce — so the override is refused with the offending revision named.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloIvaWalletOverrideFreshWalletError(*, translated_message, context=None)[source]

Bases: ModeloIvaWalletSeedError

Raised when an override would overrule fresh AEAT wallet evidence.

When a non-blocked aeat_wallet reconciliation decision already resolves the period, the live AEAT wallet/cartera is the authority for iva.compensacion-pendiente-periodos-anteriores (AEAT box 110). An operator-asserted override must not silently overrule fresh AEAT evidence, so the override is refused.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
seed_iva_compensation_period_for_bucket(*, bucket_id, period, amount)[source]

Seed local IVA compensation history for the bucket taxpayer.

Returns an IvaCompensationPeriodState stored by aeat.application.calculations.seed_iva_compensation_period(). The stored state represents an operator-declared opening carry-forward balance for a Modelo 303 period that predates local history. It is not a live AEAT wallet observation and it does not by itself authorize a Modelo 303 calculation; the wallet reconciliation/gate path still owns the effective modelo-303-compensacion-pendiente-anteriores decision.

See also

aeat.application.calculations.seed_iva_compensation_period() Pure single-writer primitive that stores the seeded period state. aeat.application.modelo._iva_wallet_gate.resolve_iva_compensation_decision_for_calculation() Gate-side resolver that requires a persisted decision before applying the prior-compensation binding.

Return type:

IvaCompensationPeriodState

Parameters:
correct_iva_compensation_period_for_bucket(*, bucket_id, period, amount, reason)[source]

Correct a wrong opening IVA compensation balance, guarded and audited.

Returns the corrected IvaCompensationPeriodState.

The seed verb is one-shot: it refuses to overwrite an existing record, so a wrong opening carry-forward balance for a pre-history period is otherwise unrecoverable. This is the deliberate correction path. It:

  • resolves the bucket’s taxpayer NIF (refusing when absent, like seed);

  • refuses a negative amount (like seed);

  • guards the filed basis: refuses when a sealed (already-filed) Modelo 303 revision at or after the seeded period consumed the seeded compensation — re-writing such a basis would silently change an already-filed return, the same filed-immutability risk the ledger restore guard enforces (ModeloIvaWalletCorrectionSealedError);

  • delegates the write to the single-writer correct_iva_compensation_period() primitive (no parallel write path), which refuses to fabricate a record where none exists (re-raised as ModeloIvaWalletCorrectionNoRecordError);

  • emits a MODELO_IVA_WALLET_CORRECTED audit event carrying the operator reason and the before/after amounts.

The local app never files; correcting the wallet basis touches no AEAT write surface.

See also

aeat.application.calculations.correct_iva_compensation_period() Single-writer primitive that replaces the stored seed after this facade’s filed-basis guard passes. aeat.domain.buckets.BucketEventType Declares the MODELO_IVA_WALLET_CORRECTED audit event emitted here.

Return type:

IvaCompensationPeriodState

Parameters:
record_iva_compensation_override_for_bucket(*, bucket_id, period, amount, reason, evidence_locator)[source]

Record an explicit taxpayer override for Modelo 303 prior compensation.

Returns the persisted IvaCompensationReconciliationDecision with the taxpayer_override source.

The Modelo 303 reconciliation refuses to AUTO-apply a seeded or local-recurrence prior-compensation balance when no live AEAT wallet evidence is available; the decision is blocked pending an explicit taxpayer override. This is the operator-facing recorder of that override. It:

  • resolves the bucket’s taxpayer NIF (refusing when absent, like seed/correct);

  • refuses a negative amount (like seed/correct);

  • guards the filed basis (ModeloIvaWalletOverrideSealedError): refuses when a sealed (already-filed) Modelo 303 revision at or after the period has already consumed that period’s compensación basis — recording an override would silently change a filed return, the filed-immutability risk the correction guard and the ledger restore guard enforce;

  • does not overrule fresh AEAT evidence (ModeloIvaWalletOverrideFreshWalletError): refuses when a non-blocked aeat_wallet decision already resolves the period;

  • builds an IvaCompensationOverride and drives reconcile_modelo_303_iva_compensation() with persist=True to store a non-blocking taxpayer_override decision keyed by period through the single decision repository; a subsequent work calculate reads it and applies the amount to iva.compensacion-pendiente-periodos-anteriores;

  • emits a MODELO_IVA_WALLET_OVERRIDE_RECORDED audit event.

reason and evidence_locator are operator-asserted audit metadata: they are recorded for the operator’s own audit trail and are NOT verified by the app to point at real evidence. The override is the taxpayer asserting, under their own responsibility, a figure the app cannot otherwise corroborate locally.

The local app never files; recording an override touches no AEAT write surface and does not relax the dependent-period verify gate, which still requires official external evidence before a dependent period can be filed.

NOTE: the persisted decision is currently NOT re-reconciled when later evidence for the period arrives (the broader sticky-decision behaviour in resolve_iva_compensation_decision_for_calculation); recording an override therefore takes precedence for the period until explicitly re-recorded or corrected. That re-reconciliation is tracked as a separate follow-up.

See also

aeat.application.calculations.reconcile_modelo_303_iva_compensation() Persists the non-blocking taxpayer-override wallet decision consumed by later Modelo 303 calculations. aeat.application.calculations.IvaWalletDecisionRepository Repository used to detect an existing fresh AEAT-wallet decision before allowing an override. aeat.application.modelo._iva_wallet_gate.require_persisted_iva_compensation_decision_matches_revision() Replay gate that ensures exported/filed revisions still match the persisted decision.

Return type:

IvaCompensationReconciliationDecision

Parameters: