cadrumo.application.calculations.iva_compensation_history module

Profile-scoped IVA compensation history built from filed Modelo 303s.

This module owns the application policy and typed state projections. A required application capability persists the state; encrypted storage and its failure modes are bound outside this module.

See also

domain.iva_compensation.carry_forward

Pure FIFO lot projection and four-year review policy.

application.calculations.iva_wallet_balance

Offline balance query built from this repository.

application.calculations.iva_wallet_reconciliation

Wallet/local-history reconciliation consumer for Modelo 303 prior compensation.

iva_compensation_period_key(period)[source]

Return the latest-state key for one Modelo 303 period.

Return type:

str

Parameters:

period (Period)

require_iva_compensation_period_coordinates_current(state, *, operation)[source]

Refuse persisted compensation state whose registry coordinate is stale.

Return type:

None

Parameters:
seed_iva_compensation_period(*, taxpayer_nif, period, amount, repository, operation, seeded_at=None)[source]

Persist a manually declared carry-forward balance for one Modelo 303 period.

Returns an IvaCompensationPeriodState.

Intended for first-time users whose historical M303 carry-forward pre-dates the local compensation history. The seeded state declares provenance=IvaCompensationStateProvenance.OPERATOR_SEED; as a non-AEAT path, it carries status is None and no AEAT expediente_id.

Raises IvaCompensationSeedConflictError if a state already exists for the specified period — seeding must not overwrite an existing record.

Return type:

IvaCompensationPeriodState

Parameters:
correct_iva_compensation_period(*, taxpayer_nif, period, amount, repository, operation, corrected_at=None)[source]

Overwrite a manually-seeded carry-forward balance for one Modelo 303 period.

Returns the corrected IvaCompensationPeriodState.

The single-writer companion of seed_iva_compensation_period(): where seeding refuses if a record already exists, correction is the deliberate re-write path for a wrong opening compensation balance whose period pre-dates local history. It writes through the same IvaCompensationHistoryRepositoryProtocol (no parallel write path), so the corrected state replaces the stored record at the same period key.

The guard that a sealed (already-filed) Modelo 303 must not have its compensation basis silently changed lives one layer up, in the modelo application facade that resolves the bucket’s taxpayer and revisions; this primitive is the unguarded write the facade delegates to once that guard has passed. It refuses to fabricate a record from nothing: an absent period is a seed, not a correction, and raises IvaCompensationSeedConflictError with a correction-on-missing marker so the facade can surface the seed-first guidance.

Return type:

IvaCompensationPeriodState

Parameters:
iva_compensation_state_from_observation_envelope(envelope, *, taxpayer_nif, provenance, expediente_id=None, status=None, source_observation_key, operation, source_artefact_sha256=None)[source]

Project one already-normalized M303 envelope into IVA history.

The history boundary accepts no bare registry or filed observation. Those shapes omit the disposition that decides the available/generated pair, so treating either as history evidence would re-introduce an ungrounded carry default. The validator rejects legacy and mismatched envelopes before this constructor can select an amount.

Return type:

IvaCompensationPeriodState

Parameters:
persist_observation_envelope_and_iva_history(*, observation_repository, history_repository, envelope, taxpayer_nif, provenance, expediente_id=None, status=None, source_observation_key, operation, source_artefact_sha256=None)[source]

Atomically persist one M303 envelope and its history projection.

The state is derived and its disposition-aware pair validated before either secure-object write is prepared. The two prepared writes then enter the shared backend’s one transaction, so a refusal or a storage failure cannot leave an observation that history did not receive, or vice versa.

Return type:

IvaCompensationPeriodState

Parameters: