aeat.domain.iva_compensation package

Public facade for pure IVA-compensation domain primitives.

This package owns the regulatory Modelo 303 carry-forward projection, the Modelo 390 year-end carry partition, the wallet reconciliation decision logic, and the wallet balance projection. The domain works with typed immutable records such as IvaCompensationPeriodState, IvaCompensationCarryForwardLot, IvaCompensationCarryForwardReport, IvaCompensationYearEndCarryPartition, and IvaWalletBalanceReport; it does not open repositories, emit bucket events, or resolve the active profile.

Compensation availability is derived by derive_303_compensation_available() and then projected through build_iva_compensation_carry_forward_report() / enforce_iva_compensation_four_year_window(). Reconciliation records such as IvaCompensationOverride, IvaCompensationAuthoritySource, and IvaCompensationReconciliationDecision separate AEAT wallet evidence, filed-history evidence, local recurrence, and taxpayer override before Modelo 303 consumes casilla 110. reconcile_iva_compensation_wallet() and validate_wallet_matches_snapshot() apply that reconciliation policy against a live wallet observation conforming to IvaCompensationWalletObservationProtocol.

Repositories, secure-object custody, live wallet acquisition, and bucket event emission remain application responsibilities.

See also

application.calculations.IvaCompensationHistoryRepository

Encrypted local period-state history consumed by carry reconstruction.

application.calculations.IvaWalletDecisionRepository

Persisted wallet-authority decisions selected before Modelo 303 calculation consumes casilla 110.

application.calculations

Application source resolvers for previous-filing carries, IVA wallet decisions, and Modelo 390 annual carry partitioning.

application.live

Read-only AEAT wallet and filed-history capture surface that supplies external evidence without performing live writes.

application.modelo

Work-unit calculation and IVA-wallet gate that apply the persisted authority decision to registry snapshots.

adapters.persistence.profile.buckets.BucketEventHistoryRepository

Bucket audit trail for persisted decisions and capture orchestration, outside this pure domain package.

Submodules

• aeat.domain.iva_compensation._balance module
  • IvaWalletBalanceReport
    • IvaWalletBalanceReport.as_of_year
    • IvaWalletBalanceReport.total_balance
    • IvaWalletBalanceReport.active_balance
    • IvaWalletBalanceReport.expired_balance
    • IvaWalletBalanceReport.lot_count
    • IvaWalletBalanceReport.next_expiry_year
    • IvaWalletBalanceReport.unallocated_applied_amount
  • build_iva_wallet_balance_report()
• aeat.domain.iva_compensation._carry_forward module
  • IvaCompensationExpiryReviewState
    • IvaCompensationExpiryReviewState.ACTIVE
    • IvaCompensationExpiryReviewState.EXPIRY_REVIEW_DUE
    • IvaCompensationExpiryReviewState.EXPIRED_REVIEW_REQUIRED
  • IvaCompensationPeriodState
    • IvaCompensationPeriodState.taxpayer_nif
    • IvaCompensationPeriodState.filing_year
    • IvaCompensationPeriodState.period
    • IvaCompensationPeriodState.expediente_id
    • IvaCompensationPeriodState.status
    • IvaCompensationPeriodState.presented_at
    • IvaCompensationPeriodState.prior_pending_amount
    • IvaCompensationPeriodState.applied_amount
    • IvaCompensationPeriodState.pending_for_later_amount
    • IvaCompensationPeriodState.period_result_amount
    • IvaCompensationPeriodState.final_result_amount
    • IvaCompensationPeriodState.generated_amount
    • IvaCompensationPeriodState.available_end_amount
    • IvaCompensationPeriodState.source_observation_key
    • IvaCompensationPeriodState.source_artefact_sha256
  • IvaCompensationCarryForwardLot
    • IvaCompensationCarryForwardLot.taxpayer_nif
    • IvaCompensationCarryForwardLot.source_filing_year
    • IvaCompensationCarryForwardLot.source_period
    • IvaCompensationCarryForwardLot.generated_amount
    • IvaCompensationCarryForwardLot.applied_amount
    • IvaCompensationCarryForwardLot.remaining_amount
    • IvaCompensationCarryForwardLot.age_years
    • IvaCompensationCarryForwardLot.expiry_review_state
    • IvaCompensationCarryForwardLot.source_observation_key
  • IvaCompensationCarryForwardReport
    • IvaCompensationCarryForwardReport.as_of_year
    • IvaCompensationCarryForwardReport.lots
    • IvaCompensationCarryForwardReport.unallocated_applied_amount
  • derive_303_compensation_available()
  • build_iva_compensation_carry_forward_report()
  • IvaCompensationYearEndCarryPartition
    • IvaCompensationYearEndCarryPartition.filing_year
    • IvaCompensationYearEndCarryPartition.last_period_amount
    • IvaCompensationYearEndCarryPartition.generated_not_in_last_amount
    • IvaCompensationYearEndCarryPartition.total_year_remaining_amount
  • derive_iva_compensation_year_end_carry_partition()
  • enforce_iva_compensation_four_year_window()
  • iva_compensation_period_sort_key()
• aeat.domain.iva_compensation._errors module
  • IvaCompensationCarryForwardPolicyError
    • IvaCompensationCarryForwardPolicyError.code
  • IvaCompensationSeedConflictError
    • IvaCompensationSeedConflictError.code
  • IvaCompensationYearRangeError
    • IvaCompensationYearRangeError.code
  • IvaCompensationDecimalParseError
    • IvaCompensationDecimalParseError.code
  • IvaCompensationCasillaReferenceError
    • IvaCompensationCasillaReferenceError.code
  • IvaCompensationReconciliationInputError
    • IvaCompensationReconciliationInputError.code
  • IvaWalletReconciliationError
    • IvaWalletReconciliationError.code
• aeat.domain.iva_compensation._reconciliation module
  • IvaCompensationOverride
    • IvaCompensationOverride.amount
    • IvaCompensationOverride.reason
    • IvaCompensationOverride.evidence_locator
    • IvaCompensationOverride.recorded_at
  • IvaCompensationAuthoritySource
    • IvaCompensationAuthoritySource.source_kind
    • IvaCompensationAuthoritySource.amount
    • IvaCompensationAuthoritySource.source_locator
    • IvaCompensationAuthoritySource.captured_at
    • IvaCompensationAuthoritySource.source_modelo
    • IvaCompensationAuthoritySource.source_filing_year
    • IvaCompensationAuthoritySource.source_periods
  • IvaCompensationReconciliationDecision
    • IvaCompensationReconciliationDecision.taxpayer_nif
    • IvaCompensationReconciliationDecision.target_year
    • IvaCompensationReconciliationDecision.target_period
    • IvaCompensationReconciliationDecision.selected_authority
    • IvaCompensationReconciliationDecision.selected_amount
    • IvaCompensationReconciliationDecision.wallet_amount
    • IvaCompensationReconciliationDecision.local_recurrence_amount
    • IvaCompensationReconciliationDecision.override_amount
    • IvaCompensationReconciliationDecision.divergence
    • IvaCompensationReconciliationDecision.blocked
    • IvaCompensationReconciliationDecision.stale_wallet
    • IvaCompensationReconciliationDecision.reason
    • IvaCompensationReconciliationDecision.wallet_captured_at
    • IvaCompensationReconciliationDecision.authority_sources
    • IvaCompensationReconciliationDecision.decided_at
  • IvaCompensationWalletObservationProtocol
    • IvaCompensationWalletObservationProtocol.taxpayer_nif
    • IvaCompensationWalletObservationProtocol.target_year
    • IvaCompensationWalletObservationProtocol.target_period
    • IvaCompensationWalletObservationProtocol.total_pending
    • IvaCompensationWalletObservationProtocol.source_url
    • IvaCompensationWalletObservationProtocol.captured_at
  • LocalIvaCompensationRecurrenceProtocol
    • LocalIvaCompensationRecurrenceProtocol.amount
    • LocalIvaCompensationRecurrenceProtocol.binding_id
    • LocalIvaCompensationRecurrenceProtocol.source_kind
    • LocalIvaCompensationRecurrenceProtocol.source_modelo
    • LocalIvaCompensationRecurrenceProtocol.source_filing_year
    • LocalIvaCompensationRecurrenceProtocol.source_periods
    • LocalIvaCompensationRecurrenceProtocol.resolved_at
  • reconcile_iva_compensation_wallet()
  • local_recurrence_authority_source()
  • validate_wallet_matches_snapshot()