cadrumo.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 relation_prefill binding providers) from previous_filing bindings (declared as BindingDefinition 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 CalculationObservationRepositoryProtocol and returns BindingPrefillReport coverage.

UNKNOWN_SOURCE_COORDINATE

The token a rendered source coordinate carries when the coordinate is not known.

Rendered provenance must stay readable as a coordinate triple, so the unknown axis is named rather than left blank: an empty segment reads as a coordinate that was looked up and found empty.

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:

data (Any)

binding_id: BindingId
value: Decimal
dependency_treatment: str

The registry’s declared dependency treatment for this carry, empty when the revision declares none. A factual_evidence carry is a fact to reconcile against rather than a figure that settles the return, and a consumer must be able to tell it from a direct_annual_settlement one. Carried here rather than gated here: the value is NOT withheld, because a taxpayer is entitled to a suffered retención and dropping it silently is an over-declaration. Empty means the revision declared no treatment, which is not the same as any particular one and must never be read as one.

provenance: str
source_kind: str
source_modelo: str | None

The prior filing this value was carried from, or None when the binding resolved outside any registry requirement and its provider names no source coordinate. None is the honest answer for “not known”; an empty string would read as a modelo whose code happens to be blank.

source_filing_year: int | None
source_periods: tuple[str, ...]
source_registry_snapshot_refs: tuple[RegistrySnapshotRef, ...]
resolved_at: datetime
class UnsatisfiedBinding(**data)[source]

Bases: BaseModel

One previous_filing binding the local store could not supply a value for.

Carries the coordinates the operator needs to act: which prior filing was looked for, and for which year and periods. Emitted so an unsatisfiable carry is reported rather than dropped – every previous_filing carry is a liability-reducing quantity (a payment already made, a loss carried forward, a prior valuation baseline), so a silent one produces a return declaring more tax than is owed and looking entirely ordinary while it does so.

Parameters:

data (Any)

binding_id: BindingId
source_modelo: str
source_filing_year: int
source_periods: tuple[str, ...]
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; unsatisfied names the declared previous_filing bindings the store supplied nothing for, which the same resolver projects onto the diagnostics channel.

Parameters:

data (Any)

prefilled: tuple[PrefilledBinding, ...]
binding_values: Mapping[BindingId, Decimal]
unsatisfied: tuple[UnsatisfiedBinding, ...]
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:

data (Any)

binding_id: BindingId
amount: Decimal
source_kind: str
source_modelo: str
source_filing_year: int
source_periods: tuple[Period, ...]
source_registry_snapshot_refs: tuple[RegistrySnapshotRef, ...]
resolved_at: datetime
source_locator: str | None
observation_from_iva_compensation_history(state, *, operation)[source]

Project secure IVA compensation history into the registry resolver contract.

Return type:

RegistryModeloObservation

Parameters:
iva_compensation_history_observation(*, modelo_id, revision_id, casillas, formulas, casilla_id, value, operand_refs=(), operand_values=())[source]

Project one IVA history casilla, failing if registry provenance is missing.

Return type:

tuple[CasillaObservation, ...]

Parameters:
resolve_bindings_from_local_store(snapshot, *, operation, repository, iva_history_repository, 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:
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.

See also

PreviousFilingSourceResolver adapts this report to CalculationSourceResolution; resolve_relations_from_local_store() resolves the separate relation_prefill source family over the same observation repository.

extract_modelo_303_local_iva_compensation_recurrence(snapshot, *, operation, repository, iva_history_repository, captured_at=None)[source]

Extract the local Modelo 303 compensation recurrence for comparison.

This is the explicit wallet-feeding path over IvaCompensationHistoryRepositoryProtocol: it reconstructs the local previous-filing amount so reconcile_modelo_303_iva_compensation() can compare it with current AEAT wallet evidence.

Parameters:
Return type:

tuple[LocalIvaCompensationRecurrence | None, BindingPrefillReport]

The returned amount is the locally reconstructed prior compensation balance for the target Modelo 303 period. Callers must feed it into reconciliation; they must not use it directly as the effective value while fresh AEAT wallet evidence exists.

Returns a 2-tuple of a LocalIvaCompensationRecurrence (or None when no compensation binding is present) and the underlying BindingPrefillReport.