cadrumo.application.prorrata_register.service module

Application service for the cross-period IVA prorrata register.

Thin orchestration over the application-owned ProrrataRegisterServiceRepositoryProtocol: the caller declares a per-ejercicio prorrata entry, lists the register, and reads one entry by (ejercicio, sector) key. The register is authoritative profile-scoped state; this service owns no calculation, only the declare/list/get surface. The LIVA arts. 102-106 compute substrate lives in the pure domain module domain.iva, and the precedence-ladder resolution lives in domain.prorrata_register.

The seed from the stamped prior settlement observation (art. 105.Uno), the provenance-tagged art. 105.Dos/Tres overrides, and the settlement write-back are built on top of this facade in later waves; this module is only the persistence surface they compose over.

See also

domain.prorrata_register

Pure register records and the precedence-ladder resolver.

adapters.persistence.profile.prorrata_register

FINANCIAL secure-object repository that stores the profile-scoped register singleton.

domain.iva

Legal IVA prorrata substrate that supplies the definitive percentage and the art. 105.Cuatro regularisation cuota.

require_prorrata_register_coordinates_current(register, *, operation)[source]

Re-confirm every registry-derived coordinate before register values are read.

Return type:

ProrrataRegister

Parameters:
require_prorrata_entry_coordinates_current(entry, *, operation)[source]

Re-confirm one entry’s registry coordinates before it joins the register.

Checked on the entry alone: wrapping it in a one-entry register would run the register’s cross-year lifecycle rules without the stored prior years.

Return type:

None

Parameters:
class ProrrataRegisterService(*, repository, operation)[source]

Bases: object

Declare, list, and read cross-period prorrata entries on the active profile.

Parameters:
declare(entry)[source]

Atomically add or replace entry by its (ejercicio, sector) key.

Parameters:

entry (ProrrataRegisterEntry) – The per-ejercicio prorrata entry to persist.

Return type:

ProrrataRegister

Returns:

The updated ProrrataRegister.

declare_especial_transition(entry)[source]

Persist one current-period prorrata-especial option or revocation.

The typed evidence is mandatory for this authoring path. The register model enforces its regime, same-ejercicio mutual-exclusion, reference, and prior-especial lifecycle invariants during the repository’s atomic singleton rebuild.

Return type:

ProrrataRegister

Parameters:

entry (ProrrataRegisterEntry)

record_aeat_autorizada(*, ejercicio, provisional_percentage, authorisation_reference, sector_id=None, regime=None)[source]

Record an art. 105.Dos AEAT-authorised provisional prorrata override.

Parameters:

  • ejercicio (int) – Filing year whose provisional prorrata is authorised.

  • provisional_percentage (Decimal) – AEAT-authorised provisional deduction percentage.

  • authorisation_reference (str) – Operator-held reference for the AEAT authorisation.

  • sector_id (str | None) – Optional sector identifier for sectores diferenciados.

  • regime (ProrrataRegisterRegime | None) – Prorrata regime in force for the entry. Defaults to general.

Return type:

ProrrataRegister

Returns:

The updated ProrrataRegister.

record_inicio_actividad(*, ejercicio, provisional_percentage, proposal_reference, sector_id=None, regime=None)[source]

Record an art. 105.Tres start-of-activity provisional override.

proposal_reference identifies the operator-held proposal or filing evidence supporting the declared percentage. The registry supplies the typed provenance token so callers cannot manufacture a vocabulary value outside the pinned authority.

Return type:

ProrrataRegister

Parameters:
declare_sector(definition)[source]

Atomically add or replace a differentiated-sector definition by sector_id.

The operator’s art. 9.1.c partition is a legal judgment the ledger cannot infer, so it is declared here; once at least one sector is declared the register is sectorized and the per-sector apportionment routing applies (LIVA arts. 9.1.c / 101). Existing per-ejercicio entries are preserved.

Parameters:

definition (SectorDefinition) – The differentiated-sector partition entry to persist.

Return type:

ProrrataRegister

Returns:

The updated ProrrataRegister.

list_all()[source]

Return the full active-profile register.

Return type:

ProrrataRegister

Returns:

A ProrrataRegister; empty when nothing has been declared.

get(ejercicio, *, sector_id=None)[source]

Return the entry for a (ejercicio, sector) key, or None when absent.

Parameters:

  • ejercicio (int) – Filing year to look up.

  • sector_id (str | None) – Sector identifier, or None for the whole-entity entry.

Return type:

ProrrataRegisterEntry | None

Returns:

The matching ProrrataRegisterEntry, or None.

resolve_provisional(ejercicio, *, sector_id=None, candidate_entries=())[source]

Resolve the in-force provisional percentage through the single declared ladder.

The persisted register carries at most one entry per (ejercicio, sector). Seed and override flows can supply same-key transient candidates so the application lookup still resolves through the domain ladder (AEAT_AUTORIZADA > INICIO_ACTIVIDAD > CARRIED_PRIOR_DEFINITIVA) rather than open-coding precedence here.

Parameters:

  • ejercicio (int) – Filing year to resolve.

  • sector_id (str | None) – Sector identifier, or None for the whole-entity entry.

  • candidate_entries (Iterable[ProrrataRegisterEntry]) – Additional same-key entries from seed/override resolution that have not necessarily been persisted yet.

Return type:

ProrrataProvisionalResolution

Returns:

The domain ProrrataProvisionalResolution.