cadrumo.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 gain the official-AEAT capability.

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 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.

persist_observation_envelope_and_iva_history():

Atomically co-emits local Modelo 303 observations and IVA history.

require_filing_result_disposition(*, work_unit, result_disposition)[source]

Refuse a Modelo 303 filing whose result disposition was never resolved.

The disposition is a determined fact resolved once at the calculate/file boundary by resolve_modelo_result_disposition. This is a PRESENCE requirement and never a second derivation: recomputing it here would make a regulated determination answerable in two places, which is how the fichero an operator submits and the carry a later period reads come to disagree.

Declared as a callable rather than left inline because the same condition has to hold at two positions in one filing transition: ahead of the first repository write, where a refusal leaves every catalogue untouched, and again at the observation write itself, which other callers reach directly. Two copies of the condition would be two authorities on when a filing is under-declared, and they would drift.

Return type:

None

Parameters:
class PreparedFiledRevisionObservation(payload, key, history_repository)[source]

Bases: object

A validated filed-revision observation that no write has consumed yet.

Parameters:
payload: ObservationEnvelopePayload
key: str
history_repository: IvaCompensationHistoryRepositoryProtocol | None
prepare_filed_revision_observation(*, revision, work_unit, repository, captured_at, result_disposition=None, prior_domiciliation_election=None, taxpayer_nif=None, filing_record_id=None, iva_compensation_history_repository)[source]

Validate a filed revision’s observation without writing it.

Every refusal the observation write can raise – a missing disposition, a split storage context, carry ingress, displacing captured AEAT evidence – is raised here, so a filing transition can run it ahead of its own writes and never be refused after the filing has landed.

Core types: CalculationRevision.

Return type:

PreparedFiledRevisionObservation

Parameters:
filed_revision_observation_writes(prepared, *, repository, taxpayer_nif, filing_record_id)[source]

Return the writes placing a prepared filed-revision observation, for an outer unit of work.

The observation lands in the pending-local layer; a locally filed Modelo 303 with a taxpayer NIF also projects its IVA compensation history row. Both are prepared before the caller commits, so a refusal leaves nothing written.

Return type:

tuple[SecureObjectWrite, ...]

Parameters:
persist_filed_revision_observation(*, revision, work_unit, repository, captured_at, result_disposition=None, prior_domiciliation_election=None, taxpayer_nif=None, filing_record_id=None, iva_compensation_history_repository, prepared=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 CalculationObservationRepositoryProtocol 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 (CalculationObservationRepositoryProtocol) – 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.

  • result_disposition (ResultDisposition | None) – The single typed Tipo de declaración resolved at the filing boundary. Required for Modelo 303 carry ingress and retained with app_filing provenance in the persisted envelope.

  • prior_domiciliation_election (PriorDomiciliationElectionProjection | None) – Safe semantic election and, when the marker is X, its official baseline-U join. It never contains account data and is retained on the local filing observation.

  • 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 only to distinguish the source_observation_key. APP_FILING provenance is declared by the required enum.

  • iva_compensation_history_repository (IvaCompensationHistoryRepositoryProtocol) – Required repository capability for the Modelo 303 history projection.

  • prepared (PreparedFiledRevisionObservation | None) – The observation prepare_filed_revision_observation() already validated for this filing; prepared here when omitted.

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 persist_observation_envelope_and_iva_history() together with IvaCompensationHistoryRepositoryProtocol; 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.

See also

CalculationObservationRepositoryProtocol:

Stores the non-official cross-period observation envelope.

IvaCompensationHistoryRepositoryProtocol:

Stores the profile-local Modelo 303 compensation period state.

extract_modelo_303_local_iva_compensation_recurrence():

Reads the local IVA history for wallet reconciliation.