cadrumo.application.calculations.errors module

Typed exception hierarchy for the calculations application layer.

These exceptions are raised by previous-filing, binding-prefill, IVA compensation, and encrypted observation-repository services at the application boundary. Every class inherits from CoreError; validation failures use CoreValidationError so CLI and API callers receive registry-backed envelopes instead of generic ValueError or TypeError failures.

Every refusal raised across this package carries a registered locale key plus machine facts; no raise site authors an operator-facing sentence, so str(exc) renders the key and the prose is resolved once, per locale, at the presentation boundary.

A narrow subset is additionally a safety disposition: the calculation observed evidence whose contradiction cannot be resolved by choosing one side, because either choice silently changes a declared amount. Those raise sites attach a PreconditionVerdict whose no_recovery_outcome is SAFETY, so the CLI boundary projects an explicit “there is deliberately no recovery here” instead of manufacturing a retry that would re-derive the same contradiction.

See also

application.calculations.binding_prefill:

Previous-filing binding readers that raise BindingPrefillTypeError.

application.calculations.iva_compensation_history:

Modelo 303 IVA compensation carry-forward readers that raise IvaCompensationModeloError.

application.calculations.observations_repository:

Encrypted observation storage that raises ObservationKeyError and ObservationCasillaReferenceError.

class CalculationRefusalPrecondition(*values)[source]

Bases: StrEnum

Closed failed-condition identities for calculation safety dispositions.

Membership is deliberately narrow. A condition earns a place here only when the refusal reports two sources of the same declared amount that disagree, so no automatic remedy exists: resolving it means deciding which figure the taxpayer actually declared, which is an operator judgement made against AEAT’s own record. An evidence-incomplete refusal an operator fixes by supplying better evidence is not a safety disposition and stays a plain typed refusal.

M303_CARRY_DISPOSITION_CONSISTENT
M303_CARRY_DERIVATION_CONSISTENT
M303_CARRY_MATCHES_REGISTRY_FORMULA
calculation_no_recovery_verdict(condition, *, facts, outcome=NoRecoveryOutcome.SAFETY)[source]

Return one explicitly non-actionable outcome for a calculation refusal.

The facts name exactly what the two disagreeing sources reported; the closed outcome is what stops a downstream boundary from manufacturing a recovery command that would simply re-derive the same contradiction. No action is bound because none of these conditions has a safe automatic remedy.

Parameters:
Return type:

PreconditionVerdict

Returns:

The PreconditionVerdict carrying the failed condition and its explicit no-recovery outcome.

exception IvaCompensationModeloError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreError

Raised when a non-Modelo 303 observation is passed to IVA compensation history.

The IVA compensation carry-forward pipeline is exclusively sourced from Modelo 303 filed observations. Passing any other modelo to iva_compensation_state_from_observation_envelope() violates the calculation boundary contract.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception BindingPrefillTypeError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreValidationError

Raised when a binding selector field carries an unexpected runtime type.

Binding selectors flow through pydantic with a union value type, so static analysis loses the per-key shape. This error is raised by the selector narrowing helpers in application.calculations.binding_prefill. It protects resolve_bindings_from_local_store() from selector values that do not match the expected int | str or str | tuple[str, ...] shape.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ObservationKeyError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreValidationError

Raised when an observation key component fails its repository contract.

The repository key for a (modelo, filing_year, period) triple must satisfy safe_repository_id() for string components and fall within the supported year range [2000, 2099] for the integer year component. The key builders in application.calculations.observations_repository raise this error instead of a bare ValueError so failures propagate through the typed error registry and produce structured envelopes.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ObservationCasillaReferenceError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreValidationError

Raised when a persisted filing observation names undeclared casillas.

CalculationObservationRepositoryProtocol is the encrypted calculation-history substrate for cross-period and cross-modelo reads. It must not persist a RegistryModeloObservation whose casilla keys are only syntactically valid CasillaId strings; every key must be declared by the resolved RegistrySnapshot for that modelo, year, and period via undeclared_casilla_ids().

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code