aeat.application.modelo._filed_revision_observation module¶

Persist a locally-filed calculation revision as a cross-period observation.

This is the local-filing sibling of the live-AEAT-capture persistence path (persist_filed_calculation_observation()). It does NOT introduce a parallel write path: it is an additional projection of the single-writer filing transition (persist_filed_revision()), co-emitted with MODELO_FILED, that records the filed CalculationRevision outputs into the cross-period observation store so a later period’s calculate can carry them forward automatically via the previous_filing resolver.

The persisted observation is stamped with a NON-official source_kind (app_filing): a value an operator filed through the app is not external AEAT evidence. The cross-period clean-state guard (_cross_period_clean_state) treats any source_kind outside its official set as the LOCAL_FILING_MISSING_EXTERNAL_EVIDENCE blocker, so this carry feeds calculate/draft but never satisfies the filing gate for a dependent period — filing still requires real external evidence. app_filing MUST NOT be added to _OFFICIAL_SOURCE_KINDS.

Non-goal (grupo per_grupo_member fan-in): this helper persists the single-filer (modelo, filing_year, period) row only. It does not stamp a member_nif and therefore does not feed the cross-member fan-in the 353<-322 aggregation enumerates; member-row persistence for the local filing flow is out of scope (ADR 2026-06-09-modelo-iva-routing-carry ruling D4) and remains a live-capture concern.

The projection reads CalculationRevision observations, rewrites the affected CasillaObservation rows for refunded Modelo 303 filings, and persists a RegistryModeloObservation record.

See also

persist_filed_revision():: Calls this projection after the filing catalogue write and MODELO_FILED event succeed.
resolve_previous_filing_binding_values():: Consumes stored RegistryModeloObservation rows for previous_filing bindings during calculation.
_cross_period_clean_state:: Classifies app_filing as non-official evidence for filing-grade readiness.
iva_compensation_state_from_registry_observation():: Projects local Modelo 303 observations into the IVA compensation history.

APP_FILING_SOURCE_KIND: Final¶

Non-official source_kind stamped on locally-filed observations.

Deliberately NOT a member of aeat.application.calculations._cross_period_clean_state._OFFICIAL_SOURCE_KINDS: a locally-filed value is not external AEAT evidence and must never satisfy the cross-period clean-state filing gate. See ADR 2026-06-09-modelo-iva-routing-carry ruling D1.

persist_filed_revision_observation(*, revision, work_unit, repository, captured_at, refunded=False, taxpayer_nif=None, filing_record_id=None, iva_compensation_history_repository=None)[source]¶

Persist a filed revision’s casilla observations as a cross-period record.

Projects the filed revision’s provenance-bearing CalculationRevision observations (every casilla — inputs, bound, and computed alike, each already carrying legal_refs / source_refs / formula provenance) into a single RegistryModeloObservation keyed by the work unit’s (modelo, filing_year, period) and saves it through the bucket-scoped CalculationObservationRepository with the NON-official source_kind = "app_filing".

Parameters:

revision (CalculationRevision) – The just-filed CalculationRevision whose typed observations are projected.
work_unit (WorkUnit) – The revision’s parent WorkUnit, supplying the (modelo, filing_year, period) key.
repository (CalculationObservationRepository) – The bucket-scoped observation repository (the same instance the filing transition threads through, so the write lands in the active bucket’s encrypted store).
captured_at (datetime) – The filing timestamp, stamped on the stored record.
refunded (bool) – When True and the work unit is Modelo 303, the filed period was disposed as a refund request (devolución, Tipo de declaración D): the generated compensación credit is excluded from carry, so the persisted iva.compensacion-disponible-fin-periodo (and the per-period generada casilla) are zeroed for the generated component before the carry row is written. The default False preserves the standard compensación carry. Legal basis: RD 1624/1992 art. 30 / Ley 37/1992 art. 116.
taxpayer_nif (str | None) – Taxpayer NIF from the active profile. When supplied for a locally filed Modelo 303, the same observation is projected into the profile-local IVA compensation history repository.
filing_record_id (str | None) – Local filing record id used as non-AEAT provenance for the IVA compensation history state.
iva_compensation_history_repository (IvaCompensationHistoryRepository | None) – Optional repository override for the Modelo 303 history projection.

Return type:

str

Returns:

The (modelo, filing_year, period) observation key string the record was stored under.

The saved RegistryModeloObservation feeds later calculations through the registry previous_filing path, but its source_kind = "app_filing" keeps it outside official evidence. For locally filed Modelo 303 rows with a taxpayer NIF, the same observation is also converted into an IvaCompensationPeriodState via iva_compensation_state_from_registry_observation() and saved through IvaCompensationHistoryRepository; that history is read only by the explicit IVA-wallet recurrence comparison path, not as a second direct owner of the effective casilla 110 value.