cadrumo.domain.calculations.registry.irnr_ledger_bindings module

Modelo 210 explicit-IRNR ledger binding contract.

The selected ModeloRevision declares the bindings this module validates and resolves. 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 M210 selector, its target_casilla_id match predicate, the single-fact gross_income_amount aggregation, and the zero-amount false-fire guard.

class LedgerIrnrIncomeProvider(**data)[source]

Bases: BaseModel

Validated selector for a Modelo 210 gross-income ledger binding.

Parameters:

data (Any)

kind: Literal[BindingSourceKind.LEDGER_IRNR_INCOME_AGGREGATION]
modelo: Modelo
target_casilla_id: CasillaId
fact: Literal['gross_income_sum']
source_jurisdictions: tuple[CountryCodeAlpha2, ...]

Source jurisdictions whose income the binding admits; any other source is out of scope.

ledger_irnr_income_source_jurisdictions(revision, *, target_casilla_id)[source]

Return the source-jurisdiction scope the revision declares for target_casilla_id.

None means the revision declares no single scope for the target, which callers must treat as an unavailable declaration rather than an open scope.

Core types: ModeloRevision.

Return type:

frozenset[str] | None

Parameters:
validate_ledger_irnr_income_aggregation_binding_definition(binding)[source]

Validate a ledger_irnr_income_aggregation binding definition.

Return type:

None

Parameters:

binding (BindingDefinition)

validate_ledger_irnr_income_aggregation_binding(binding)[source]

Validate a ledger_irnr_income_aggregation binding at registry-build time.

Return type:

list[str]

Parameters:

binding (BindingDefinition)

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

Bases: Protocol

Structural protocol for one selected M210 gross-income observation.

property target_casilla_id: CasillaId

Return the casilla this observation’s gross income is routed to.

property gross_income_amount: Decimal

Return the observed gross income amount.

resolve_ledger_irnr_income_aggregation_binding_values(revision, observations)[source]

Resolve Modelo 210 gross-income bindings from selected M210 observations.

Delegates the filter/aggregate skeleton to resolve_ledger_family_binding_values(), shared by every ledger family resolver.

Parameters:
Return type:

dict[TypeAliasType, Decimal]

Returns:

Binding ids mapped to their selected gross-income totals.

Raises:

RegistryValidationError – If a declared binding has a malformed selector.

unsupported_ledger_irnr_income_observations(revision, observations)[source]

Return non-zero M210 observations no declared source binding consumes.

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 _irnr_income_build_matcher) and a zero-gross_income_amount false-fire guard. No extra_exclusion.

Parameters:
Return type:

tuple[IrnrIncomeObservationProtocol, ...]

Returns:

Non-zero observations that no declared binding consumes.

Raises:

RegistryValidationError – If a declared binding has a malformed selector.