cadrumo.domain.calculations.registry.convenio module

Cross-cutting Convenio doble imposición (CDI) treaty-override authority.

A development compiler reads the registry authoring surface into the immutable artifact. This runtime module retains only the resulting treaty authority types that any IRNR rate formula consumes through the RegistrySnapshot — so a second consumer (M216 retenciones a no residentes) reads treaty data without reaching across a modelo boundary.

Each override row carries a typed ConvenioOverrideKind so the “más favorable” / limitation-of-benefits decision is computed rather than coincidental: flat replaces the domestic rate, ceiling applies min(domestic, treaty), allocation_domestic_tariff delegates the amount to the domestic tariff, and exempt drives the source-state rate to zero.

class ConvenioOverrideRow(**data)[source]

Bases: RegistryModel

One per-income-type treaty override keyed by TipoRentaIrnr.

The typed ConvenioOverrideKind decides how the row acts on the domestic IRNR rate. flat and ceiling rows MUST declare a rate in [0, 1]; allocation_domestic_tariff and exempt rows MUST NOT (the amount is delegated to the domestic tariff or driven to zero). The legal_ref_anchor MUST be one of the row’s legal_refs and resolve to a treaty article in the shared legal/ catalogue.

Parameters:
tipo_renta: TipoRentaIrnr
kind: ConvenioOverrideKind
rate: str | None
legal_ref_anchor: LegalRefId
legal_refs: tuple[LegalRefId, ...]
notes: str | None
valid_from: date
valid_to: date | None
property rate_decimal: Decimal | None

The parsed rate for a rate-bearing kind, else None.

class ConvenioTreaty(**data)[source]

Bases: RegistryModel

One bilateral double-taxation treaty and its per-income-type overrides.

Projected from the canonical irnr.convenio.override governed fact and keyed by the counterpart country_code (ISO 3166-1 alpha-2). The optional permanent-establishment / employment-income surfaces are deliberately not modelled yet; the schema leaves room for them without foreclosing.

Parameters:
country_code: str
document_id: str
overrides: tuple[ConvenioOverrideRow, ...]
notes: str | None
class ConvenioOverride(**data)[source]

Bases: RegistryModel

The resolved treaty override returned by ConvenioAuthority.resolve().

A flat projection of the matched ConvenioOverrideRow bound to its treaty’s country_code and document_id — the shape the IRNR rate op and the modelo verification sweep branch on. rate is populated only for the rate-bearing kinds (flat / ceiling).

Parameters:

data (Any)

country_code: str
document_id: str
tipo_renta: TipoRentaIrnr
kind: ConvenioOverrideKind
rate: Decimal | None
legal_refs: tuple[LegalRefId, ...]
class ConvenioAuthority(**data)[source]

Bases: RegistryModel

The compiled cross-cutting treaty authority projected onto every snapshot.

Owns the {country_code: ConvenioTreaty} map and the single resolve() lookup any IRNR rate formula consumes. Projected onto the RegistrySnapshot the same way the shared legal/ catalogue is, so the treaty override is one branch of the single tipo-de-gravamen resolution path, never a parallel rate mechanism.

Parameters:

treaties (Annotated[Mapping[str, ConvenioTreaty], <cadrumo.core.frozen_mapping.FrozenMappingMarker object at 0x7f8c00a93860>])

treaties: Annotated[Mapping[str, ConvenioTreaty], FROZEN_MAPPING]
classmethod empty()[source]

Return a ConvenioAuthority with no treaties (the no-override default).

Return type:

ConvenioAuthority

resolve(country_code, tipo_renta, year)[source]

Return the ConvenioOverride for (country_code, tipo_renta, year), or None.

None means no treaty row applies — the caller keeps the domestic baseline (no country declared) or raises the missing-row BLOCKING sentinel (a treaty country was declared but carries no row for the filed income type), never a silent blank.

Return type:

ConvenioOverride | None

Parameters:
class ResolvedConvenioOverride(kind, rate, country_code, document_id, fact)[source]

Bases: object

One provider-selected treaty override with legal provenance.

Parameters:
kind: ConvenioOverrideKind
rate: Decimal | None
country_code: str
document_id: str
fact: ResolvedOverrideFact
property is_exempt: bool

Whether the selected registry row drives the source rate to zero.

property has_flat_rate: bool

Whether the selected registry row replaces the domestic rate.

property has_ceiling_rate: bool

Whether the selected registry row caps the domestic rate.

property delegates_to_domestic_tariff: bool

Whether the selected registry row delegates to the domestic tariff.

resolve_convenio_override(*, country_code, tipo_renta, devengo_date, operation)[source]

Resolve and validate the exact dated treaty fact, or return no row.

Registry corruption, an ambiguous selection, unsupported payloads, and missing legal provenance remain registry refusals. Only the absence of a matching dated selector is represented by None.

Return type:

ResolvedConvenioOverride | None

Parameters: