aeat.application.calculations._binding_prefill module¶

Binding prefill: resolve previous_filing bindings from prior filings.

Used by PreviousFilingSourceResolver for the source-mesh calculation path and by extract_modelo_303_local_iva_compensation_recurrence() for the IVA wallet comparison path.

One of three distinct prefill tiers, NOT to be merged: this is the PREVIOUS-FILING direct-carry tier. The other two are the relation tier (_relation_prefill) and the AEAT borrador pre-fill tier (the registry aeat_prefilled flag, an AEAT-live source). They share only the word “prefill”; each routes a different source through a different mechanism.

Sister module to _relation_prefill. The runtime distinguishes relation leaves (cross-revision aggregations declared as RelationDefinition records) from previous_filing bindings (declared as DataBindingDefinition with source = "previous_filing"). Modelo 390 uses bindings — modelo 200 uses relations — both express “sum a prior modelo’s casilla across periods” but route through different schema entities.

Prior-filing values are gathered as CasillaObservation records and merged inside RegistryModeloObservation rows before the binding is resolved.

The strict registry boundary remains previous_filing_observation_requirements() and resolve_previous_filing_binding_values(); this module is the application reader that supplies local observations from CalculationObservationRepository and returns BindingPrefillReport coverage.

class PrefilledBinding(**data)[source]¶

Bases: BaseModel

One resolved previous-filing binding with local-source provenance.

Emitted by resolve_bindings_from_local_store() and collected in BindingPrefillReport. The source_* fields point back to the RegistryModeloObservation rows that satisfied the registry previous-filing requirement.

Parameters:

binding_id (BindingId)
value (Decimal)
provenance (str)
source_kind (str)
source_modelo (str)
source_filing_year (int)
source_periods (tuple[str, ...])
resolved_at (datetime)

binding_id: BindingId¶

value: Decimal¶

provenance: str¶

source_kind: str¶

source_modelo: str¶

source_filing_year: int¶

source_periods: tuple[str, ...]¶

resolved_at: datetime¶

class BindingPrefillReport(**data)[source]¶

Bases: BaseModel

Outcome of one direct previous-filing binding-prefill pass.

binding_values is the mapping passed to calculate_registry_snapshot(); prefilled keeps the PrefilledBinding provenance used by PreviousFilingSourceResolver when stamping source-mesh results.

Parameters:

prefilled (tuple[PrefilledBinding, ...])
binding_values (Mapping[BindingId, Decimal])

prefilled: tuple[PrefilledBinding, ...]¶

binding_values: Mapping[BindingId, Decimal]¶

class LocalIvaCompensationRecurrence(**data)[source]¶

Bases: BaseModel

Local Modelo 303 recurrence evidence extracted for wallet reconciliation only.

This is comparison evidence. It does not choose the effective casilla 110 value; the IvaWalletDecisionSourceResolver and wallet reconciliation decision remain the only selectors.

Parameters:

binding_id (BindingId)
amount (Decimal)
source_kind (str)
source_modelo (str)
source_filing_year (int)
source_periods (tuple[Period, ...])
resolved_at (datetime)
source_locator (str | None)

binding_id: BindingId¶

amount: Decimal¶

source_kind: str¶

source_modelo: str¶

source_filing_year: int¶

source_periods: tuple[Period, ...]¶

resolved_at: datetime¶

source_locator: str | None¶

resolve_bindings_from_local_store(snapshot, *, repository=None, iva_history_repository=None, captured_at=None, activity_start_date=None, excluded_binding_ids=None)[source]¶

Resolve every previous_filing binding the revision declares against observations in the local store.

The caller provides a RegistrySnapshot; this function asks the registry for RegistryFoldRequirement records, loads matching RegistryModeloObservation rows, then delegates the final value calculation to resolve_previous_filing_binding_values().

Parameters:

snapshot (RegistrySnapshot) – The RegistrySnapshot whose revision’s previous_filing bindings are resolved from the local calculation observation store.
repository (CalculationObservationRepository | None) – Optional CalculationObservationRepository; defaults to the active-bucket repository when None.
iva_history_repository (IvaCompensationHistoryRepository | None) – Optional IvaCompensationHistoryRepository consulted for the IVA compensation prior-balance bindings; defaults to the active-bucket repository when None.
captured_at (datetime | None) – Optional capture timestamp recorded on the produced prefill records; defaults to the canonical clock when None.
activity_start_date (date | None) – Optional operator-declared activity start. Source periods strictly before this date are no-prior-obligation periods and resolve to a neutral zero instead of requiring observed filings.
excluded_binding_ids (frozenset[TypeAliasType] | None) – Optional previous-filing binding ids to leave unresolved because another authority owns them.

Return type:

BindingPrefillReport

Returns a BindingPrefillReport carrying the resolved binding_values mapping (suitable for passing through calculate_registry_snapshot’s binding_values= argument) plus a tuple of PrefilledBinding records with provenance per entry.

Bindings the local store cannot satisfy are skipped silently — the engine emits blank cells the operator fills by hand. Strict enforcement (refusing the export when prior filings are missing) is the caller’s choice via the prefill report’s coverage.