aeat.application.modelo._revision_persistence module

Repository mutation helpers for modelo calculation and filing transitions.

The calculate path stores draft CalculationRevision rows with their provenance-bearing CasillaObservation entries, advances the parent WorkUnit pointer, and emits modelo.calculation.created through the BucketEventHistoryRepository catalogue. The event is a lightweight join record; full legal/source provenance remains on the persisted calculation revision’s observations, with has_provenance signalling that the join is grounded.

The filing path runs here only after its caller has passed readiness, workflow, and clean-state gates. It records the local/internal filing transition: create a current ModeloRecord, supersede any prior current filing for the work target, move calculation revisions into PRESENTADO states, and co-emit the TransactionRevisionParticipationIndex writes, cross-period observation projections, and Modelo 303 settlement prorrata register writeback. It never submits to AEAT and never turns the non-official app_filing carry projection into filing-grade external evidence.

See also

file_modelo_revision():

Orchestrates preconditions and result-disposition resolution before delegating successful mutations here.

import_external_filing_evidence():

Separate import boundary that creates current records with ExternalEvidence; this persistence helper deliberately creates local records without that payload.

persist_filed_revision_observation():

Projects filed casilla observations into non-official cross-period carry evidence.

ProrrataRegisterRepository:

Profile-scoped encrypted repository co-emitted for Modelo 303 settlement prorrata writeback.

ProrrataRegisterEntry:

Typed row updated with definitive percentage and annual volume inputs.

emit_bucket_event(*, repository, bucket_id, event_type, occurred_at, actor, object_type, object_id, payload)[source]

Append one BucketEvent to the bucket-event-history catalogue.

The returned event is the durable bucket-scoped audit pointer for the domain mutation. Payloads stay compact and reference the owning calculation revision, filing record, or work unit instead of duplicating their full catalogued state.

Return type:

BucketEvent

Parameters:
persist_calculation_revision(*, work_unit_id, work_unit, work_units, input_values_by_casilla_id, binding_overrides, row_binding_values, relation_overrides, casilla_values, source_transaction_ids, borrador_snapshot_id, bindings_sourced_from_borrador, observations, unresolved_outcomes=(), source_provenance=(), detail_rows, formula_count, actor, now, calculation_repository, work_unit_repository, bucket_event_repository)[source]

Persist a freshly calculated draft revision and return the CalculationRevision.

Returns the existing duplicate when an identical revision is already persisted. The content-addressed revision id includes manual casilla inputs, binding/relation overrides, ledger source transactions, borrador provenance, detail rows, and calculated casilla values. The supplied CasillaObservation rows carry the legal and source provenance persisted with a new calculation revision.

The source_provenance tuple carries the resolver-level source-mesh trace (CalculationSourceRef rows projected from the calculation source mesh) so the persisted revision records which resolver mesh and which upstream source objects produced it. It is additive and does NOT participate in derive_calculation_revision_id.

The emitted BucketEvent uses the revision id as object_id and includes a has_provenance payload flag plus a source_provenance_count and an order-independent source_provenance_trace_sha256 digest of the source-mesh trace. Audit readers can therefore use the event as a compact pointer back to the persisted CalculationRevision, and detect a source-connectivity change from the digest without decrypting the revision, instead of treating bucket history as the standalone provenance store.

Return type:

CalculationRevision

Parameters:
persist_filed_revision(*, target, work_unit, work_units, notes, actor, now, calculation_repository, filing_repository, work_unit_repository, bucket_event_repository, calculation_observation_repository=None, participation_index_repository=None, prorrata_register_repository=None, refunded=False, taxpayer_nif=None)[source]

Persist a verified-complete calculation revision and return a ModeloRecord.

The caller has already run verification/workflow/readiness gates. The target CalculationRevision is the verified-complete source revision that becomes PRESENTADO when this transition succeeds. The parent WorkUnit is advanced to the new current filing record after the calculation and filing catalogues are saved.

When calculation_observation_repository is supplied, the filed revision’s observations are co-emitted with MODELO_FILED through persist_filed_revision_observation(), so later calculations can carry them through the previous_filing resolver. The record is stamped with NON-official app_filing and never satisfies the cross-period clean-state filing gate; use import_external_filing_evidence() when the current record must carry ExternalEvidence.

refunded is resolved once at the calculate/file boundary by resolve_modelo_result_disposition. For refunded Modelo 303 filings (devolución, Tipo de declaración D), it tells persist_filed_revision_observation() to persist ZERO compensación carry; the default False preserves standard carry (RD 1624/1992 art. 30 / Ley 37/1992 art. 116).

For Modelo 303 settlement periods, the filed definitive prorrata percentage and annual volume inputs are also co-emitted to the profile ProrrataRegister through ProrrataRegisterRepository in the same secure-object save as the filing catalogue and filed calculation revision.

Return type:

ModeloRecord

Parameters: