cadrumo.domain.deadlines.models module

Pydantic v2 strict models for the cadrumo.domain.deadlines subpackage.

Every type that crosses a public boundary lives here as a strict, frozen pydantic.BaseModel (or enum.StrEnum for closed enumerations). No dataclasses; no bare dict[str, Any].

Consumers import these models from this defining module.

class IVARegime

Bases: str

Opaque registry-projected IVA regime token.

Membership, deadline applicability, descriptions, and legal references are selected from the 0098 IVA schema-vocabulary fact. This type retains only the stable public string token shape.

property value: str

Return the opaque token for string-oriented serialization.

class IrpfIncomeCategory(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque IRPF income-category token projected from fact 0128.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class IrpfEstimationRegime(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque IRPF estimation-regime token projected from the facts registry.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class IrpfActivityKind(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque IRPF activity-kind token projected from fact 0082.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class IrpfSpecialRegime(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque IRPF special-regime token projected from the facts registry.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class ObligationStatus(*values)

Bases: StrEnum

Status of a single ModeloDeadline against a reference date.

UPCOMING and DUE_SOON are differentiated by the CADRUMO_DEADLINE_DUE_SOON_DAYS setting (default 14 days). FILED and NOT_APPLICABLE are reserved for downstream consumers — the engine never produces them.

Variables:

• UPCOMING – Window opens in the future or is open but more than due_soon_days ahead of close.

• DUE_SOON – Window closes within due_soon_days of the reference date.

• DUE_TODAY – Reference date is the close date.

• OVERDUE – Reference date is past the close date.

• FILED – Downstream marker for filings already submitted.

• NOT_APPLICABLE – Downstream marker for obligations the profile no longer triggers.

UPCOMING

DUE_SOON

DUE_TODAY

OVERDUE

FILED

NOT_APPLICABLE

class ModeloEnrollment(**data)

Bases: BaseModel

AEAT enrollment facts used by registry filing schedules.

Parameters:

data (Any)

large_company: bool

public_administration_budget_gt_6000000: bool

class RefundAccount(**data)

Bases: BaseModel

The cuenta-devolución refund account AEAT pays a Modelo 303 refund into.

Refund-only. AEAT’s DR303 position 23 is a single dual-purpose field labelled Domiciliación/Devolución - IBAN, so the record has somewhere to state a charge account too – but this profile carries no separate charge account, and the export path must not infer one by reusing this account for a domiciliación del ingreso: nominating an account to RECEIVE a refund is not an authorisation to DEBIT it. The export path refuses that election unconditionally rather than make the inference.

Groups the IBAN with the foreign-bank block used for a non-SEPA account. Every field is sensitive financial identity data: per the sensitive-financial-data-secure-storage-only invariant it lives only in the encrypted secure-object store (sensitivity="financial" on the profile schema), is read transiently into memory at export time, and is never written to plaintext, logs, or a side store.

The IBAN is validated structurally at this boundary — country code, check digits, BBAN length, and the ISO 13616 mod-97 residue — so a malformed IBAN is rejected on input rather than deferred to fichero-write time.

Variables:

• iban – The refund account IBAN (canonical, whitespace- and hyphen-stripped, upper-cased). None when no refund account is on file.

• swift_bic – SWIFT-BIC of the bank for a non-SEPA account.

• bank_name – Bank name for a non-SEPA (Resto Países) account.

• bank_address – Bank address for a non-SEPA account.

• bank_city – Bank city for a non-SEPA account.

• bank_country_code – ISO 3166-1 alpha-2 country code of the bank for a non-SEPA account.

• sepa_marca – The derived Marca SEPA token ("1" Cuenta España / "2" UE SEPA / "3" Resto Países). Derived from the account country at export, not an operator input.

Parameters:

data (Any)

iban: str | None

swift_bic: str

bank_name: str

bank_address: str

bank_city: str

bank_country_code: str

sepa_marca: str

class ChargeAccount(**data)

Bases: BaseModel

The cuenta de cargo AEAT may debit for a Modelo 303 domiciliación.

This is deliberately distinct from RefundAccount. The DR303 DID page has one IBAN position labelled Domiciliación/Devolución - IBAN, but that is a slot chosen by the filing’s disposition, not authority to infer that a refund destination may be debited. A charge account therefore contains exactly the affirmative debit instruction the operator recorded: one IBAN and no refund-only SWIFT, foreign-bank, or SEPA-mark fields.

Like the refund account, this financial identity data exists only in the encrypted secure-object store and is read transiently when the export is composed. It is never logged or copied to a plaintext side store.

Variables:

iban – The authorised debit-account IBAN, canonicalised to the ISO 13616 whitespace- and hyphen-stripped upper-case form.

Parameters:

data (Any)

iban: str

class M303TaxTerritory(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque Modelo 303 territory token projected from fact 0098.

The facts registry owns territory membership, descriptions, and the downstream attribution semantics. This type intentionally has no Python member list; callers must obtain a token through the typed registry resolver.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class M303RegimeComposition(value, *, _registry_validated=False)

Bases: StrictRegistryToken

Opaque Modelo 303 regime-composition token projected from fact 0098.

Parameters:

• value (str)

• _registry_validated (bool)

Return type:

Self

class ModeloIVAProfile(**data)

Bases: BaseModel

IVA facts used by registry filing schedules.

Variables:

• roi_enrolled – Registered on the Registro de Operadores Intracomunitarios (ROI / VIES).

• oss_enrolled – Enrolled in the OSS / IOSS one-stop-shop regime.

• group_member_enrolled – Enrolled as a member entity in the IVA group-of-entities special regime; this is the Modelo 322 role.

• group_dominant_entity_enrolled – Enrolled as the dominant entity of an IVA group-of-entities regime; this is the Modelo 353 role.

• intracommunity_operations_exceed_50000_eur – Modelo 349 cadence threshold.

• sii_enrolled – Enrolled in the SII (Suministro Inmediato de Información) — the near-real-time IVA ledger-submission system created by RD 596/2016. Mandatory for the monthly IVA collective; voluntary for everyone else. This records SII membership only; Modelo 303 monthly cadence is driven by monthly-liquidation facts such as REDEME or large-company status, not by voluntary SII alone.

• redeme_enrolled – Registered in REDEME (Registro de Devolución Mensual del IVA) — one of the mandatory-SII triggers.

• refund_account – The encrypted cuenta-devolución refund account AEAT pays a Modelo 303 refund into. None when no refund account is on file; a refund disposition with no refund account is refused at export rather than emitting an empty DID block.

• charge_account – The encrypted cuenta de cargo AEAT may debit when the operator elects domiciliación del ingreso. It is intentionally separate from refund_account; a U export with no recorded charge account is refused rather than reusing a refund destination.

Parameters:

data (Any)

tax_territory: M303TaxTerritory

regime_composition: M303RegimeComposition

roi_enrolled: bool

oss_enrolled: bool

group_member_enrolled: bool

group_dominant_entity_enrolled: bool

intracommunity_operations_exceed_50000_eur: bool

sii_enrolled: bool

redeme_enrolled: bool

cash_accounting_regime_enrolled: bool

voluntary_sii_enrolled: bool

hydrocarbon_deposit_advance_payment_deduction_entitled: bool

refund_account: RefundAccount | None

charge_account: ChargeAccount | None

class CrossPeriodGroupMemberRoster(**data)

Bases: BaseModel

Expected member roster for a grouped cross-period dependency.

The roster is profile state, not a calculation artefact: grouped aggregate modelos such as Modelo 353 must know the complete member population before they can prove that every required upstream member filing was reconciled and accepted.

Parameters:

data (Any)

source_modelo: Annotated[Modelo, BeforeValidator(_parse_modelo_identifier)]

filing_year: FilingYear

period: Period

member_nifs: tuple[SubjectTaxId, ...]

is_ue_eee_country_code(country_code)

Return True when country_code is in the EU + EEA country set.

Return type:

bool

Parameters:

country_code (str | None)

irnr_representante_fiscal_required(country_code)

Return True when an IRNR fiscal residence country requires representante fiscal.

Return type:

bool

Parameters:

country_code (str | None)

class TaxpayerProfile(**data)

Bases: BaseModel

The profile of a Spanish taxpayer for filing-deadline computation.

Carries the structured three-axis taxpayer model — entity type, tax regime, and special enrolments — alongside the flat filing facts the deadline engine consumes today.

Variables:

• tax_id – NIF / NIE / CIF, validated and normalised through the canonical SubjectTaxId contract. Deadline computation and imported schedule state carry this identity, so it runs the AEAT checksum here rather than trusting an adjacent boundary to have run it.

• entity_type – The taxpayer’s entity type (natural person, legal entity, or attribution entity). None when the operator has not yet declared it.

• declaration_roles – The filer’s ThirdPartyDeclarationRole memberships – orthogonal to entity_type and independent of it. Drives Modelo 347 claves C, D and E; empty when the operator has not declared any such role, which is the correct default for the overwhelming majority of filers.

• legal_entity_form – The recognised legal form when entity_type is LEGAL_ENTITY; None otherwise.

• irpf_income_categories – The IRPF income categories a natural person declares (rendimientos). Empty when undeclared or when the taxpayer is not a natural person.

• irpf_estimation_regime – The IRPF estimation regime for economic-activity income. None when undeclared.

• irpf_activity_kind – Whether the economic activity is profesional or sectorial, for the RIRPF art. 95 retención rate. Operator-declared and independent of the estimation regime. None when undeclared, which a consumer MUST treat as unknown rather than as either arm – the wrong arm is 15 % against 2 %.

• iva_regime – The IVA regime the taxpayer files under.

• has_employees – Whether the taxpayer pays salaries with retención.

• colegio_concertado – Whether the withholder is a colegio concertado, which Modelo 111 declares in its own header field. None when undeclared: the producer refuses to file the modelo on an undeclared value rather than assert “not a concerted school” on the operator’s behalf.

• pays_professionals_with_retencion – Whether the taxpayer pays professional fees subject to retención.

• professional_income_withholding_ge_70pct – Whether at least 70% of the taxpayer’s prior-year professional income was already subject to withholding.

• art109_activity_income_withholding_ge_70pct – Whether the Art. 109 RIRPF 70% income-coverage exception is met for covered professional, agricultural, livestock, or forestry activity income. For activity-start cases this is the current payment period coverage fact rather than a prior-year fact.

• pays_rent_with_retencion – Whether the taxpayer pays alquiler de local with retención.

• pays_capital_income_with_retencion – Whether the taxpayer pays capital-income rents subject to withholding.

• member_of_large_multinational_group – Whether the entity is the reporting parent of a multinational group above the country-by-country reporting threshold (Modelo 231).

• eu_business_seeking_spanish_iva_refund – Whether the taxpayer is an EU-established business, not established in Spanish IVA territory, requesting a refund of Spanish input IVA (Modelo 361).

• reports_client_securities_insurance_annuities – Whether the entity is a financial or insurance intermediary that must report client securities, insurance and annuities (Modelo 189).

• does_intracomunitario – Whether the taxpayer conducts operaciones intracomunitarias.

• third_party_transactions_above_347_threshold – Whether the profile exceeded the applicable third-party transaction threshold during the prior year.

• bienes_extranjero_above_threshold – Whether the taxpayer holds bienes en el extranjero above the legal threshold.

• monedas_virtuales_extranjero_above_threshold – Whether the taxpayer holds virtual currencies abroad above the Modelo 721 threshold.

• iva – IVA-specific filing facts that can change filing cadence.

• cross_period_group_member_rosters – Expected group-member rosters keyed by upstream modelo, filing year, and period. These rosters let cross-period aggregate modelos prove complete member fan-in before verification, filing, or export.

• enrollment – AEAT enrollment facts that can change filing cadence.

• notes – Free-form notes for the user. Never consumed by the engine.

• irpf_special_regime – The IRPF special regime in effect for this taxpayer. None when undeclared (treated as GENERAL by engine consumers). IMPATRIADO activates the Ley Beckham path (LIRPF Art. 93): the CLI refuses Modelo 100 in favour of Modelo 151 and the obligation engine suppresses Modelo 100 deadlines.

• special_regime_start_date – The date of the opt-in election for the special regime. Required to compute the six-year window for IMPATRIADO (RIRPF Art. 116). None when undeclared or when irpf_special_regime is GENERAL.

• fiscal_residency – Fiscal residency category. None treated as RESIDENT_IRPF by engine consumers. NON_RESIDENT_IRNR routes the taxpayer to IRNR (TRLIRNR RDLeg 5/2004 Art. 2): the engine suppresses IRPF-resident deadlines and will activate IRNR obligations (Modelos 210/216/247) when their registry entries are wired.

• country_of_fiscal_residence – ISO 3166-1 alpha-2 code of the

• when (country of fiscal residence. Required)

• is (fiscal_residency is NON_RESIDENT_IRNR; None)

• residents. (valid only for IRPF)

• ley_49_2002_special_regime_option_declared – Whether the entity has declared the Modelo 036 option for the Title II Ley 49/2002 special fiscal regime. None means undeclared.

• ley_49_2002_special_regime_option_date – Date declared for that option on Modelo 036. None means undeclared.

• ley_49_2002_special_regime_renunciation_declared – Whether the entity has declared renunciation of the Title II Ley 49/2002 special regime. None means undeclared.

• ley_49_2002_special_regime_renunciation_date – Date declared for that renunciation on Modelo 036. None means undeclared.

Parameters:

data (Any)

tax_id: SubjectTaxId

entity_type: EntityType | None

declaration_roles: frozenset[ThirdPartyDeclarationRole]

legal_entity_form: LegalEntityForm | None

irpf_income_categories: frozenset[IrpfIncomeCategory]

irpf_estimation_regime: IrpfEstimationRegime | None

irpf_activity_kind: IrpfActivityKind | None

iva_regime: IVARegime

has_employees: bool

colegio_concertado: bool | None

pays_professionals_with_retencion: bool

professional_income_withholding_ge_70pct: bool

art109_activity_income_withholding_ge_70pct: bool

pays_rent_with_retencion: bool

pays_capital_income_with_retencion: bool

objective_estimation_prior_year_gross_income_eur: Decimal | None

objective_estimation_prior_year_invoice_gross_income_eur: Decimal | None

objective_estimation_prior_year_agri_livestock_forest_gross_eur: Decimal | None

objective_estimation_prior_year_purchases_eur: Decimal | None

objective_estimation_modulos_iae_epigraph: str

objective_estimation_modulos_module_1_units: Decimal | None

objective_estimation_modulos_module_2_units: Decimal | None

objective_estimation_modulos_module_3_units: Decimal | None

objective_estimation_modulos_module_4_units: Decimal | None

objective_estimation_modulos_module_5_units: Decimal | None

objective_estimation_modulos_module_6_units: Decimal | None

objective_estimation_modulos_module_7_units: Decimal | None

does_intracomunitario: bool

third_party_transactions_above_347_threshold: bool

bienes_extranjero_above_threshold: bool

monedas_virtuales_extranjero_above_threshold: bool

iva: ModeloIVAProfile | None

cross_period_group_member_rosters: tuple[CrossPeriodGroupMemberRoster, ...]

enrollment: ModeloEnrollment

fiscal_address_cadastral_reference: str

fiscal_address_is_habitual_vivienda: bool

activity_start_date: date | None

activity_end_date: date | None

incn_prior_12_months: Decimal | None

new_entity_first_two_profit_periods: bool | None

ley_49_2002_special_regime_option_declared: bool | None

ley_49_2002_special_regime_option_date: date | None

ley_49_2002_special_regime_renunciation_declared: bool | None

ley_49_2002_special_regime_renunciation_date: date | None

tributacion_estado_porcentaje: Decimal | None

establecimiento_type: str

elected_withholding_pct: str

vivienda_office_total_m2: Decimal | None

vivienda_office_office_m2: Decimal | None

iae_epigraph: str

notes: str

irpf_special_regime: IrpfSpecialRegime | None

special_regime_start_date: date | None

fiscal_residency: FiscalResidency | None

country_of_fiscal_residence: str | None

representante_fiscal_nif: str | None

NIF/NIE of the fiscal representative in Spain.

Required when fiscal_residency is NON_RESIDENT_IRNR and the country is outside the EU/EEA (Art. 47 LGT + Art. 10 TRLIRNR RDLeg 5/2004).

representante_fiscal_nombre: str | None

Full name of the fiscal representative in Spain.

Required together with representante_fiscal_nif for the same cases.

sal_socios_trabajadores_count: int | None

sal_reserva_especial_dotada: Decimal | None

sal_capital_social: Decimal | None

irpf_pagadores_count: int | None

Number of pagadores (income payers) the taxpayer received income from.

When >= 2 and irpf_pagadores_secondary_income > 1500, filing Modelo 100 is mandatory under Art. 96.3 LIRPF regardless of the total income threshold. None when not declared (treated as “not known”).

irpf_pagadores_secondary_income: Decimal | None

Sum of income received from the 2nd and subsequent pagadores.

Art. 96.3 LIRPF: when irpf_pagadores_count >= 2 and this value exceeds €1,500, the work-income filing-exemption limit drops from the general €22,000 to the per-year reduced limit. Only meaningful when irpf_pagadores_count >= 2; None when not declared.

irpf_pagadores_total_work_income: Decimal | None

Total rendimientos íntegros del trabajo for the year (all pagadores).

Art. 96.2.a)/96.3 LIRPF: a Modelo 100 filing obligation arises when this total exceeds the applicable exemption limit — the general €22,000, or the per-year reduced limit (€15,876 for 2024 onward) when the multiple-pagadores condition is met. None when not declared, in which case a triggered multiple-pagadores condition surfaces a conservative advisory.

beckham_window_active(today)

Return whether the selected special-regime window covers today.

Return type:

bool

Parameters:

today (date)

property ue_eee_status: bool

True when country_of_fiscal_residence is in the EU + EEA (post-Brexit).

GB is excluded from 2021-01-01 (Brexit transition end). Returns False when country_of_fiscal_residence is None (i.e., for IRPF-resident profiles).

resolve_multiple_pagadores_reduced_limit(filing_year, *, facts)

Return the Art. 96.3 LIRPF reduced work-income exemption limit for filing_year.

The reduced limit is dated (14.000 € up to 2022, 15.000 € for 2023, 15.876 € for 2024 onward); the authoritative per-year schedule lives in typed governed mapping fact selected by the explicit filing-period coordinate. Missing coordinates fail closed rather than borrowing a historical or future amount.

Parameters:

• filing_year (int) – The year the work income was obtained.

• facts (DeadlineFactResolutionContext) – Authority plus explicit filing and submission coordinates.

Return type:

Decimal

Returns:

The reduced exemption limit in euros as a Decimal.

evaluate_multiple_pagadores_obligation(pagadores_count, secondary_income, total_work_income=None, *, filing_year, facts)

Return True when Art. 96.3 LIRPF mandates Modelo 100 filing.

Art. 96.2.a) LIRPF (Ley 35/2006) exempts a natural person from filing when their rendimientos íntegros del trabajo do not exceed the general 22.000 € limit. Art. 96.3 LIRPF LOWERS that limit to a reduced, dated amount (15.876 € for 2024 onward) when the work income comes from more than one pagador AND the aggregate from the 2nd-and-subsequent pagadores strictly exceeds 1.500 €. The multiple-pagadores situation never obliges a filing by itself — it only drops the exemption limit — so the obligation arises only when total work income exceeds the applicable reduced limit.

Parameters:

• pagadores_count (int | None) – Number of pagadores the taxpayer received work income from during the year. None means undeclared.

• secondary_income (Decimal | None) – Sum of income from the 2nd and subsequent pagadores. None means undeclared.

• total_work_income (Decimal | None) – Total rendimientos íntegros del trabajo for the year. None means undeclared; the obligation then cannot be ruled out, so the rule surfaces conservatively rather than granting a false clear (no-silent-under-declaration).

• filing_year (int) – The year the income was obtained, selecting the dated reduced limit.

• facts (DeadlineFactResolutionContext) – Authority plus explicit filing and submission coordinates.

Return type:

bool

Returns:

True when the reduced-limit regime is active (count >= 2 AND secondary_income > 1,500) and either total work income is undeclared or it strictly exceeds the per-year reduced limit; False in every other case, including when count or secondary income is undeclared.

class RecargoBand(**data)

Bases: BaseModel

One Ley 58/2003 art-27 recargo band projected by runtime authority.

The published typed catalogue carries the surcharge schedule for self-assessments filed after the deadline without prior AEAT notice. Each projection materialises into one RecargoBand; the Recovery value attached to an OVERDUE ModeloDeadline references the resolved band by id.

Variables:

• id – Stable identifier (completed_months_0, after_12_months, …). Used by the CLI for per-band rendering.

• min_completed_months – Inclusive lower bound on the completed-months window this band covers. Art. 27.2 LGT counts only COMPLETED months of delay; a fractional month does not count.

• max_completed_months – Inclusive upper bound, or None for the open-ended after_12_months band.

• surcharge_pct – Recargo percentage applied on the cuota.

• interest_applies – True only for the after-12-months band; the CLI renders the interest hint when set.

• legal_ref – Stable corpus reference (ley-58-2003:art-27.2).

Parameters:

data (Any)

id: str

min_completed_months: NonNegativeInt

max_completed_months: int | None

surcharge_pct: Decimal

interest_applies: bool

legal_ref: str

class Recovery(**data)

Bases: BaseModel

Operator-facing recovery payload attached to an OVERDUE obligation.

Surfaces the resolved Ley 58/2003 art-27 recargo band. The application overview layer declares any executable continuation from the resolved modelo and period; the CLI resolves that declaration against its live command surface.

Variables:

• still_filable – True for every band – art-27 self-assessments remain admissible past the original deadline; the surcharge is the only consequence. The flag exists so a future band for absolutely-time-barred filings can be added without reshaping the model.

• recargo_band – The RecargoBand resolved from the completed-months window (Art. 27.2 LGT). It carries the legal reference for the band; read it as recovery.recargo_band.legal_ref rather than mirroring it onto this payload, so there is exactly one place a renderer can read the grounding from and no way for two copies to disagree.

Parameters:

data (Any)

still_filable: bool

recargo_band: RecargoBand

class ModeloDeadline(**data)

Bases: BaseModel

A single filing obligation in a Schedule.

Variables:

• modelo – The modelo string identifier; carried as a plain str on this record so JSON round-tripping is loss-free for downstream consumers.

• period – The period covered as a typed Period (e.g. Period.from_year_and_code(2026, "1T")).

• opens_on – The first day the AEAT filing window accepts the modelo for this period.

• closes_on – The last day the AEAT filing window accepts the modelo for this period.

• payment_cutoff_on – The cutoff for direct-debit payment, if applicable. None when there is no payment leg.

• status – The ObligationStatus against the reference today used by DeadlineEngine.compute().

• applies_because – Human-readable explanation of why the profile is obliged to file this modelo, resolved from the registry deadline applicability rule.

• boe_references – Tuple of opaque BOE / Manual práctico citation keys. Stable identifiers, never URLs.

• recovery – Resolved Recovery payload when status is OVERDUE; None for every other status. Populated by the deadline engine using the days-late window and the registry’s recargo bracket table.

Parameters:

data (Any)

modelo: Annotated[Modelo, BeforeValidator(_parse_modelo_identifier)]

period: Annotated[Period, BeforeValidator(_parse_modelo_deadline_period)]

opens_on: date

closes_on: date

payment_cutoff_on: date | None

status: ObligationStatus

applies_because: str

boe_references: tuple[str, ...]

recovery: Recovery | None

class Schedule(**data)

Bases: BaseModel

The full filing schedule for a taxpayer profile for a given year.

Variables:

• profile – The TaxpayerProfile the schedule was computed for.

• year – The target year.

• obligations – Tuple of ModeloDeadline ordered by (closes_on, modelo, period).

• generated_at – UTC timestamp of when DeadlineEngine.compute() built this schedule. The only non-deterministic field, and validated as UTC-aware rather than merely documented as such: a naive or offset timestamp on filing evidence is ambiguous about the day a window opened or closed.

Parameters:

data (Any)

profile: TaxpayerProfile

year: int

obligations: tuple[ModeloDeadline, ...]

generated_at: UtcInstant