aeat.application.calculations._relation_prefill module

Relation prefill: resolve registry relations from prior filings.

One of three distinct prefill tiers, NOT to be merged: this is the RELATION tier (cross-revision aggregations declared as RelationDefinition records). The other two are the previous-filing direct-carry tier (application.calculations._binding_prefill) and the AEAT borrador pre-fill tier (the registry aeat_prefilled flag, an AEAT-live source). Each names a different mechanism and source; they share only the word “prefill”.

Sits between the engine and the local observation store. The engine asks “what’s the resolved value of every relation this revision declares?” and this module answers by consulting a RegistrySnapshot to enumerate the declared relations. The same-modelo first-period default resolver reads the relations and bindings declared on one ModeloRevision directly:

  1. Reading the revision’s relations to determine source_modelo, source_revision_selector, source_periods, source_casilla_id, and aggregation.op.

  2. Scanning the local CalculationObservationRepository for prior RegistryModeloObservation filings matching the source quadruple.

  3. Folding the source filings’ casilla values through the declared aggregation op (sum, copy).

  4. Returning a RelationValues record stamped with provenance the apply adapter writes onto the workbook so the pull adapter can detect stale prefills.

When no prior filings exist for a relation, the resolver returns a RelationValue with value=None and provenance="operator_manual" so the engine emits a blank cell the operator must fill by hand.

This is the local-tier prefill. The AEAT-live tier (parsing justificantes from Sede) lives in a separate adapter that produces the same RelationValues shape; callers route between tiers based on the operator’s preferences and the local store’s coverage.

See also

RelationPrefillSourceResolver

Source-mesh adapter that exposes resolved relations as CalculationSourceResolution.

domain.calculations.registry.relation_source_requirements()

Registry authority that derives the source filings required by a relation.

domain.calculations.registry.materialize_relation_binding_values()

Bridge from resolved relation values to declared relation_prefill binding slots.

resolve_relations_from_local_store(snapshot, *, repository=None, captured_at=None, modelo_202_first_year_cuota=False, activity_start_date=None, m111_no_retenciones_periods=None, not_applicable_source_modelos=None)[source]

Build a relation-value record from the local observation store.

Parameters:

  • snapshot (RegistrySnapshot) – The RegistrySnapshot whose declared relations are resolved from prior observation records in the local store.

  • repository (CalculationObservationRepository | None) – Optional observation repository. Defaults to the active profile’s CalculationObservationRepository.

  • captured_at (datetime | None) – Optional timestamp for relation provenance. Defaults to the current clock.

  • modelo_202_first_year_cuota (bool) – When True (IS-3), an otherwise-unresolved Modelo 202 (source_modelo == "202") fold-in relation resolves to 0 instead of None — a first-year IS filer under modalidad cuota (LIS art. 40.2) has no pago-fraccionado obligation. The caller derives this fail-closed (only for a Modelo 200 target); a resolved M202 value is never overridden.

  • activity_start_date (date | None) – When set (IRPF-1), source periods strictly before the operator’s activity start are scoped out of every relation requirement, so a mid-year-start filer folds only the quarters it actually had an obligation for instead of leaving the annual fold unresolved. None (the default / fail-closed case) keeps the full all-quarters behaviour.

  • m111_no_retenciones_periods (frozenset[tuple[int, str]] | None) – Explicit (year, period) M111 no-obligation attestations. Each named source period is removed from M111 relation folds only; unknown/non-M111 periods keep the normal filing-grade requirement.

  • not_applicable_source_modelos (frozenset[str] | None) – Source modelos positively determined as not applicable for this bucket profile. M100’s mutually exclusive M130/M131 pagos-fraccionados relations use this to resolve the absent leg to explicit zero instead of requiring fake zero filings.

Return type:

RelationValues

Returns a RelationValues whose values tuple has one RelationValue per relation declared in the snapshot’s revision, with provenance stamped per entry. Relations the local store cannot resolve get value=None and provenance="operator_manual" so the engine emits a blank cell the operator can fill by hand.

class RelationPrefillSourceResolver(*, repository=None, registry_snapshot=None, captured_at=None)[source]

Bases: object

Source-mesh adapter for local relation_prefill values.

Resolves registry relations through resolve_relations_from_local_store(), materialises resolved relation values into declared target-binding slots, and returns a CalculationSourceResolution carrying relation values, binding values, diagnostics for unresolved formula relations, and provenance for local RegistryModeloObservation filings.

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

CalculationSourceResolution

Parameters:

context (CalculationSourceContext)

relation_prefill_period_zero_default_binding_ids(revision, *, modelo, period)[source]

Return the relation-prefill binding ids calculate resolves to zero for period.

A Modelo 202 same-model previous-payment carry (previous_period relation sourcing the same modelo) has no upstream filing before its first target period, so the resolver materialises its target_binding slot as zero rather than leaving it absent. This is the single authority for “which relation-prefill bindings are pre-satisfied with a zero default in this period”; both the calculate resolver (_modelo_202_first_period_previous_payment_defaults()) and the readiness missing-bindings projection consume it, so readiness and calculate agree on the missing set by construction (one-aggregation-path-pull-equals-calculate).

Return type:

frozenset[TypeAliasType]

Parameters: