cadrumo.domain.calculations.registry.ledger_impatriado_bindings module

Impatriado (Beckham-regime) ledger income aggregation binding family.

One of the per-family modules the registry binding surface is split into: the selector model, its validators, the observation protocol, and the resolver for ledger_impatriado_income_aggregation bindings.

Separated from the general ledger-binding module so that module holds families rather than growing into a single file of them, per the per-family module shape the registry binding surface follows.

The resolver and its fail-closed screen delegate their filter/aggregate skeleton to resolve_ledger_family_binding_values() and unsupported_ledger_family_observations(), the shape shared by every ledger-aggregation family; this module supplies only the M151 selector, its target_casilla_id match predicate, the two-fact aggregation (ingresos_integros_sum with a taxable_base_amount-or-gross_amount per-observation fallback, cash_received_sum summing gross_amount unconditionally), and the declarable-amount false-fire guard.

validate_ledger_impatriado_income_aggregation_binding_definition(binding)[source]

Validate a ledger_impatriado_income_aggregation binding definition.

Return type:

None

Parameters:

binding (BindingDefinition)

validate_ledger_impatriado_income_aggregation_binding(binding)[source]

Validate a ledger_impatriado_income_aggregation binding at registry-build time.

Accumulating list[str] validator over LedgerImpatriadoIncomeProvider; runs the casilla / fact / aggregation-op invariant at build time through invariant_diagnostics(), whose raise-style body is validate_ledger_impatriado_income_aggregation_binding_definition().

Return type:

list[str]

Parameters:

binding (BindingDefinition)

class ImpatriadoIncomeObservationProtocol(*args, **kwargs)[source]

Bases: Protocol

Structural protocol for Modelo 151 impatriado Spanish-source income observations.

The registry only needs these attributes to resolve ledger_impatriado_income_aggregation bindings; the full ImpatriadoIncomeObservation satisfies this protocol without any explicit declaration.

property target_casilla_id: CasillaId

Return the Modelo 151 base casilla receiving this observation’s aggregate.

property gross_amount: Decimal

Return the observation’s gross or cash-received amount.

property taxable_base_amount: Decimal | None

Return the declared IVA-exclusive taxable base, when available.

resolve_ledger_impatriado_income_aggregation_binding_values(revision, observations)[source]

Resolve every ledger_impatriado_income_aggregation binding on revision.

The fact declared in the binding selector controls which field is summed: "ingresos_integros_sum" → observation.taxable_base_amount when declared, else observation.gross_amount; "cash_received_sum" → observation.gross_amount. Only ES-scoped observations reach this resolver; the source-scope segregation is owned by the application classifier. Delegates the filter/aggregate skeleton to resolve_ledger_family_binding_values(), shared by every ledger family resolver.

Parameters:
Return type:

dict[TypeAliasType, Decimal]

unsupported_ledger_impatriado_income_observations(revision, observations)[source]

Return ES-scoped impatriado observations no binding can consume.

revision is the ModeloRevision whose declared bindings define what is consumable. Delegates the screen to unsupported_ledger_family_observations() — see that function for the shared fail-closed contract (why an unmatched observation is a modelling gap, not a legitimate zero). This family’s own contribution is narrow: the target_casilla_id match predicate (reused from the resolver’s _impatriado_income_build_matcher) and a false-fire guard that excludes an observation whose declarable amount — max(gross_amount, taxable_base_amount) when a base is declared, gross_amount otherwise — is zero. No extra_exclusion.

Return type:

tuple[ImpatriadoIncomeObservationProtocol, ...]

Returns:

The unsupported ImpatriadoIncomeObservationProtocol rows, in input order.

Parameters:
class LedgerImpatriadoIncomeProvider(**data)[source]

Bases: BaseModel

Validated form of a ledger_impatriado_income_aggregation binding selector.

modelo is Modelo 151 (the only modelo whose base is legally source-scoped to Spanish income by art. 93.2 LIRPF). target_casilla_id is the base casilla that receives the annual Spanish-source total.

fact is REQUIRED and carries no default, matching its LedgerRentaIncomeProvider sibling. The two accepted values name different legal measures of the same rows, so a default silently picks a legal claim on the taxpayer’s behalf — and a default on one sibling but not the other re-creates exactly the divergence this requiredness closes (the two families defaulted to different facts for one concept). An omitting binding fails registry validation naming the accepted set.

fact controls which aggregation path is applied:

  • "ingresos_integros_sum" sums the fiscally computable ingreso per observation: taxable_base_amount (the IVA-exclusive base imponible) when the transaction carries an explicit IVA tagging, falling back to gross_amount when no base is declared — the canonical base path.

  • "cash_received_sum" sums gross_amount across the window, ignoring any declared taxable base. Named for what it computes: the cash the bank credited, which is neither gross of retención nor IVA-exclusive.

Parameters:

data (Any)

kind: Literal[BindingSourceKind.LEDGER_IMPATRIADO_INCOME_AGGREGATION]
modelo: Modelo
target_casilla_id: CasillaId
fact: ImpatriadoLedgerIncomeFact