aeat.application.aggregation._modelo_bindings module

Repository-backed source-mesh resolvers for modelo registry bindings.

This module is the calculation-facing bridge from bucket-local stores to CalculationSourceResolution. Each resolver owns one BindingSourceKind, reads the active CalculationSourceContext, and materialises binding values declared on the snapshot’s ModeloRevision.

The IVA, Renta income, Renta expense, and M130 gasto resolvers delegate their ledger projection to _iva_ledger, _renta_income_ledger, _renta_ledger, and _renta_gasto_ledger. The retenciones resolver reads the dedicated per-perceptor store through _retencion_observations_repository. The separate _oss_ioss and _withholding_source modules follow the same source-mesh contract for Modelo 369 and Modelo 190 detail counts.

Invoice-backed checks use InvoiceCatalogueRepository only as supporting evidence: Modelo 303 domestic IVA remains ledger-owned, while Renta expense aggregation can attach purchase-invoice evidence to transaction rows before producing the shared CalculationSourceResolution.

Declarable observations that no registry binding consumes are reported as source diagnostics rather than silently blanking the filed calculation.

class LedgerIvaAggregationSourceResolver(*, transaction_repository=None, invoice_repository=None)[source]

Bases: object

Resolve ledger_iva_aggregation bindings from the transaction ledger.

Owns BindingSourceKind.LEDGER_IVA_AGGREGATION, projects IVA observations through aggregate_iva_ledger_observations_from_repositories(), and returns a CalculationSourceResolution with source issues, unrouted-observation diagnostics, and transaction provenance.

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

class LedgerRentaExpenseAggregationSourceResolver(*, transaction_repository=None, invoice_repository=None)[source]

Bases: object

Resolve ledger_renta_expense_aggregation bindings for Renta expenses.

Owns BindingSourceKind.LEDGER_RENTA_EXPENSE_AGGREGATION and folds transaction rows plus purchase-invoice evidence through aggregate_renta_ledger_expenses_from_repositories(). It reports source issues and unrouted deductible expenses on the returned CalculationSourceResolution.

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

class LedgerRentaIncomeAggregationSourceResolver(*, transaction_repository=None)[source]

Bases: object

Resolve ledger_renta_income_aggregation actividad-income bindings.

Owns BindingSourceKind.LEDGER_RENTA_INCOME_AGGREGATION. Modelo 130 uses the cumulative-quarter income path, while Modelo 100 uses the annual activity-income path over the same ledger eligibility rules.

Parameters:

transaction_repository (TransactionCatalogueRepositoryProtocol | None)

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

class LedgerImpatriadoIncomeAggregationSourceResolver(*, transaction_repository=None)[source]

Bases: object

Resolve ledger_impatriado_income_aggregation Modelo 151 base bindings.

Owns BindingSourceKind.LEDGER_IMPATRIADO_INCOME_AGGREGATION. Modelo 151 (régimen especial de impatriados, Ley Beckham) folds only Spanish-source (source_jurisdiction == "ES") income into impatriado.base-liquidable-general over the full ejercicio; every foreign-source or jurisdiction-unresolved row is segregated by the classifier into a typed BECKHAM_FOREIGN_SOURCE_SEGREGATED issue and surfaced as a non-blocking source diagnostic rather than silently admitted or silently dropped (art. 93.2 LIRPF / art. 25.1.f TRLIRNR).

Parameters:

transaction_repository (TransactionCatalogueRepositoryProtocol | None)

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

class LedgerRentaGastoAggregationSourceResolver(*, transaction_repository=None)[source]

Bases: object

Source mesh resolver for repository-backed M130 deductible-expense (gasto) bindings.

Owns BindingSourceKind.LEDGER_RENTA_GASTO_AGGREGATION. This is the OUTGOING sibling of LedgerRentaIncomeAggregationSourceResolver: it folds deductible business expenses into Modelo 130 casilla 02 over the same cumulative year-to-date quarterly window and emits an unrouted-observation diagnostic for declarable gastos no binding consumes.

Parameters:

transaction_repository (TransactionCatalogueRepositoryProtocol | None)

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

aggregation_period_for_modelo(*, filing_year, code)[source]

Translate a canonical StandardPeriodCode token to a core period.

Accepts only the span-shaped canonical AEAT tokens the calc engine and the CLI ledger filter share: quarters (1T-4T), the annual period (0A), and months (01-12). The result is the typed core Period consumed by ledger filters. Any other token raises AggregationValidationError.

Return type:

Period

Parameters:

  • filing_year (int)

  • code (str)

class RetencionesAggregationSourceResolver(*, retencion_repository=None)[source]

Bases: object

Source mesh resolver for the dedicated per-perceptor retención store (RET-1).

Reads the bucket-scoped per-perceptor retención observations (RetencionObservationRepository) for the modelo’s period and materialises the declared retenciones aggregation bindings through the matching validated aggregator. Modelo 115 consumes the quarterly URBAN_RENTAL count/base; annual summary modelos consume the same family store for their distinct-NIF count. Modelo 190’s percepciones count is handled by WithholdingSourceResolver.

Parameters:

retencion_repository (RetencionObservationRepository | None)

resolver_id
owned_sources: tuple[BindingSourceKind, ...]
static aggregate(modelo, observations, *, period)[source]

Aggregate per-perceptor retención observations for modelo.

The ONE canonical retenciones aggregation entry point. Both this resolver’s live calculate path (resolve()) and the per-modelo aggregation service (aggregate_per_modelo(), the CLI aggregate / pull surface) route through this single method over the shared _RETENCIONES_AGGREGATORS dispatch, so the calculate and pull surfaces produce byte-identical aggregation and cannot drift (one-aggregation-path-pull-equals-calculate). Raises KeyError for a non-retenciones modelo, matching the prior service dispatch.

Return type:

RetencionesAggregation

Parameters:
resolve(context)[source]
Return type:

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)