aeat.application.calculations._multi_year module

Enrollment evidence and the previous-filing source-mesh adapter.

The enrollment surface records the real renta years exercised by continuity tests through EnrollmentRecorder, emits EnrollmentEvidence, and checks those observations against the ModeloAuthorizationEntry claimed by the bundled authorization manifest.

The calculation surface is PreviousFilingSourceResolver, the source mesh adapter for PREVIOUS_FILING. It selects the caller’s RegistrySnapshot, delegates local observation reading to resolve_bindings_from_local_store(), and returns a CalculationSourceResolution for the aggregation mesh.

The direct value-resolution contract lives in _binding_prefill; this module records enrollment proof and adapts its BindingPrefillReport into source-mesh output.

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

Bases: CoreValidationError

Raised when an enrollment recording is missing its un-fakeable evidence.

Calculation-mode recordings require a strictly-positive produced-value count (a real calculation emitted casillas); non-calculation-mode recordings require both a non-empty context label AND a strictly-positive persisted-observation count (at least one real RegistryModeloObservation was saved to the real CalculationObservationRepository for that year). A recording that supplies a label alone — without a persisted observation count — is label-only and therefore fakeable; the recorder refuses it.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class EnrollmentYearObservation(**data)[source]

Bases: BaseModel

One renta year an enrolling test proved the backend exercised.

Variables:

  • modelo – The modelo id whose backend was exercised.

  • filing_year – The distinct renta (annual) year exercised.

  • calculation_mode – True when the year was produced by a real calculation (calculate_modelo_revision / registry calculate); False for the non-calculation two-year-context registration used by informativa / reconciliation / structural modelos.

  • produced_value_count – For calculation mode, the number of casilla values the real calculation produced — strictly positive, the evidence a calculation actually ran. Zero for non-calculation mode.

  • context_label – For non-calculation mode, the named real two-year context the test constructed (e.g. a fidelity-comparison label). Empty for calculation mode.

  • persisted_observation_count – For non-calculation mode, the number of RegistryModeloObservation records the test actually persisted to the real CalculationObservationRepository for this year — must be strictly positive, the evidence a real repository interaction occurred. Zero for calculation mode. Mirrors the role of produced_value_count in calculation mode: a context-mode year claimed with zero persisted observations is label-only and therefore fakeable; the recorder refuses it.

Parameters:

  • modelo (str)

  • filing_year (int)

  • calculation_mode (bool)

  • produced_value_count (int)

  • context_label (str)

  • persisted_observation_count (int)

modelo: str
filing_year: int
calculation_mode: bool
produced_value_count: int
context_label: str
persisted_observation_count: int
property has_evidence: bool

Return whether this observation carries its mode’s required evidence.

class EnrollmentEvidence(**data)[source]

Bases: BaseModel

The verified cross-year evidence an enrolling test produced for one modelo.

Constructed by EnrollmentRecorder.evidence(). The >=2 distinct renta years invariant is enforced here so an enrollment that did not actually span two distinct years cannot construct — the contract is unconstructable to violate, mirroring ModeloAuthorizationEntry.

Parameters:
modelo: str
observations: tuple[EnrollmentYearObservation, ...]
property distinct_renta_years: tuple[int, ...]

Return the distinct renta years exercised, sorted ascending.

class EnrollmentRecorder(modelo)[source]

Bases: object

Accumulates the renta years an enrolling test proves the backend exercised.

The enrolling test constructs one recorder per modelo, records each year it drives through the real backend, then calls evidence() to obtain the verified EnrollmentEvidence and assert it against the modelo’s manifest claim. The recorder is the natural home named by the modelo-multiyear-renta ADR for the un-fakeable enrollment contract.

Parameters:

modelo (str)

property modelo: str

Return the modelo id this recorder enrolls.

record_calculation_year(*, filing_year, produced_value_count)[source]

Record a renta year produced by a real calculation.

Parameters:

  • filing_year (int) – The renta year the test calculated.

  • produced_value_count (int) – The number of casilla values the real calculation emitted. MUST be strictly positive — it is the evidence a calculation actually ran for this year.

Raises:

EnrollmentEvidenceError – When produced_value_count is not strictly positive (no real calculation output to evidence the year).

Return type:

None

record_context_year(*, filing_year, context_label, persisted_observation_count)[source]

Record a renta year exercised through a real non-calculation context.

For informativa / reconciliation / structural modelos that do not run a numeric calculation, the enrolling test still drives the real adapters for the year and names the context it constructed. To be un-fakeable the call must supply both a non-blank context_label AND a strictly positive persisted_observation_count — the number of RegistryModeloObservation records actually saved to the real CalculationObservationRepository for this year. A label alone is not sufficient evidence: any string can be passed without touching the real adapters. The observation count proves a real repository interaction happened; it mirrors the role of produced_value_count in record_calculation_year().

Parameters:

  • filing_year (int) – The renta year the test exercised.

  • context_label (str) – A non-empty label naming the real two-year context (e.g. "347-fidelity-year-over-year").

  • persisted_observation_count (int) – The number of RegistryModeloObservation records the test saved to the real CalculationObservationRepository for this year. MUST be strictly positive — it is the evidence a real adapter interaction occurred.

Raises:

EnrollmentEvidenceError – When context_label is blank or when persisted_observation_count is not strictly positive.

Return type:

None

evidence()[source]

Return the verified cross-year evidence accumulated so far.

The recorder validates the >=2 distinct renta years floor here so the public API raises the documented EnrollmentEvidenceError directly; EnrollmentEvidence re-enforces the same invariant at its own type boundary as an unconstructable-to-violate backstop (a pydantic ValidationError there would wrap this error type).

Return type:

EnrollmentEvidence

Returns:

The verified EnrollmentEvidence.

Raises:

EnrollmentEvidenceError – When fewer than two distinct renta years were recorded.

assert_enrollment_matches_manifest(evidence, *, repository_root=None)[source]

Assert recorded enrollment evidence matches the modelo’s manifest claim.

The enrolling end-to-end test calls this after recording its years. It is the load-bearing cross-check that converts the manifest from an honour claim into a verified one: the recorded distinct-year set MUST equal the manifest entry’s declared renta_years on ModeloAuthorizationEntry. A mismatch (the test exercised different years than the manifest claims) raises, turning the enrolling test RED.

Parameters:
Raises:

EnrollmentEvidenceError – When no manifest entry enrolls the modelo, or the recorded distinct-year set differs from the claimed renta_years.

Return type:

None

class PreviousFilingSourceResolver(*, repository=None, registry_snapshot=None, excluded_binding_ids=None)[source]

Bases: object

Source mesh resolver for source = "previous_filing" calculation bindings.

Registered under resolver_id = "previous_filing" in the source mesh and claiming PREVIOUS_FILING. When the calculation engine encounters a binding whose source is "previous_filing", this resolver reads the relevant prior-year RegistryModeloObservation records from the local CalculationObservationRepository through resolve_bindings_from_local_store(), then maps them into the CalculationSourceResolution binding channel. Storage-degradation errors (classification, decryption, version) are caught and returned as a storage_degradation_resolution() rather than propagated.

Parameters:
resolver_id
owned_sources: tuple[BindingSourceKind, ...]
resolve(context)[source]
Return type:

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)