cadrumo.application.modelo.filing_actions module

Filing-record actions for modelo calculation revisions.

file_modelo_revision() promotes a verified CalculationRevision into a current ModeloRecord after the WorkflowEngine preflight gate passes. Filing transitions and audit entries are persisted through the application-owned bucket-event capability shared by the modelo revision services.

The action records the operator’s local/internal filing state only. It never submits to AEAT, never marks AEAT acceptance, and never fabricates official external evidence. A successful transition sets the target revision to PRESENTADO, creates a VIGENTE ModeloRecord with aeat_accepted=False, and delegates cross-period carry projection to persist_filed_revision(), which stamps locally-filed observations as non-official app_filing evidence.

See also

import_external_filing_evidence():

Separate AEAT-attested import path that creates ExternalEvidence baselines; this local filing action deliberately does not.

persist_filed_revision():

Persists the filing catalogue, revision state, work-unit pointers, bucket events, participation index rows, and optional carry observation.

persist_filed_revision_observation():

Projects filed casillas into non-official cross-period observations.

resolve_modelo_result_disposition():

Resolves the shared Modelo 303 refund/carry disposition before the file transition persists.

cadrumo.application.modelo.verification_actions._require_cross_period_clean_state:

Rechecks cross-period dependencies before local filing state is written.

exception ModeloFilingEvidenceMissingError(message=None, *, context=None, translated_message=None, precondition_failure=None)[source]

Bases: ModeloPreconditionErrorMixin, ModeloError

Raised when internal filing would seal deductible IVA without evidence.

Parameters:
Return type:

None

code
file_modelo_revision(calculation_revision_id, *, certificate_secret_backend_factory, operator_scope_ports, ports, actor, workflow_profile, operation, notes=None, refund_election=RefundElection.COMPENSAR, payment_election=PaymentElection.INGRESO, prior_domiciliation_election=PriorDomiciliationElection.KEEP, cross_period_expected_member_sets=(), workflow_engine=None, workflow_runs_dir=None, settings=None, clock=None, profile=None)[source]

Mark a verified-complete revision as the current internal filed answer.

This is the application service behind aeat app modelo work file. It is a local state transition, not an AEAT presentation: the resulting ModeloRecord has aeat_accepted=False and no external evidence.

Preconditions and state changes:

  1. Verify the revision is in VERIFICADO_COMPLETO state.

  2. Recheck profile readiness, persisted Modelo 303 IVA-wallet decision compatibility, and cross-period clean state.

  3. Run the WorkflowEngine gate for the revision’s modelo and period.

  4. Resolve the Modelo 303 result disposition from RefundElection, PaymentElection, and TaxpayerProfile.

  5. If a prior current filing exists, mark its ModeloRecord as SUPERSEDIDO and its prior CalculationRevision as PRESENTADO_SUPERSEDIDO.

  6. Create the new filing record with status VIGENTE and transition the target calculation revision from VERIFICADO_COMPLETO to PRESENTADO.

  7. Advance the work unit’s filed_calculation_revision_id and current_filing_record_id pointers, emit MODELO_FILED/ MODELO_FILED_SUPERSEDED bucket events, and persist any local app_filing carry observation.

Parameters:

  • calculation_revision_id (TypeAliasType) – The id of the verified-complete revision to file.

  • certificate_secret_backend_factory (CertificateSecretBackendFactory) – Factory for the encrypted certificate-secret capability used by workflow authentication.

  • operator_scope_ports (OperatorScopePorts) – Operator-scope capabilities used by workflow authentication.

  • actor (str) – Operator identifier recorded in the filing record and audit trail.

  • workflow_profile (TaxpayerProfile) – The TaxpayerProfile used to evaluate WorkflowEngine gate conditions and cross-period clean-state applicability.

  • notes (str | None) – Optional operator-supplied filing notes.

  • refund_election (RefundElection) – The operator’s per-filing Modelo 303 negative-result disposition election. Defaults to COMPENSAR (carry the credit forward). DEVOLVER requests the credit back as a refund and is honoured only when the period is a lawful refund period (the year’s last filing period for a non-REDEME taxpayer; every period for REDEME). An out-of-window DEVOLVER is refused.

  • payment_election (PaymentElection) – The operator’s positive-result settlement election. INGRESO is the default, DOMICILIACION is available only for Modelo 303, and CUENTA_CORRIENTE remains explicitly refused until its AEAT capability is grounded.

  • prior_domiciliation_election (object) – Whether to preserve the prior direct debit or request its cancellation/modification. The latter is accepted only for an M303 rectificativa with the official baseline-U proof.

  • ports (FilingActionPorts) – Complete application-owned filing capability bundle. It supplies the work-unit, calculation, filing, verification, observation, IVA-wallet, bucket-event, and workflow-run authorities for the active profile bucket.

  • operation (PinnedAuthorityOperation) – Caller-owned generation-pinned indexed authority operation.

  • cross_period_expected_member_sets (Iterable[CrossPeriodExpectedMemberSet]) – Optional expected grupo member rosters used by the cross-period clean-state proof.

  • workflow_engine (WorkflowEngine | None) – Optional workflow engine override for the preflight gate.

  • workflow_runs_dir (Path | None) – Optional workflow runs directory override.

  • settings (Settings | None) – Optional settings override.

  • clock (datetime | None) – Optional UTC timestamp override.

  • profile (ModeloWorkProfile | None) – The work profile the calling command already loaded for the revision’s bucket. When omitted, this entry loads it once; every profile read below uses that record.

Return type:

ModeloRecord

Returns:

The newly created local ModeloRecord in VIGENTE status.

Raises:

See also

persist_filed_revision():

Performs the repository writes once all gates pass.

import_external_filing_evidence():

Creates official-evidence baselines for imported filings; use that path when a ExternalEvidence reference must be carried.

persist_filed_revision_observation():

Saves the non-official app_filing observation used by later previous_filing calculations.

export_modelo_revision():

Sibling local finish line that writes the fichero-BOE artefact without requiring this internal file marker.

list_filing_records(*, ports, bucket_id=None, modelo=None, include_superseded=False)[source]

List ModeloRecord rows, optionally filtered to a bucket and modelo.

Superseded records are excluded unless include_superseded is true. Results are sorted by (bucket_id, filing_year, modelo, period, filed_at).

Return type:

tuple[ModeloRecord, ...]

Parameters:
get_filing_record(filing_record_id, *, ports)[source]

Return the ModeloRecord for the given id, or raise.

Return type:

ModeloRecord

Parameters:
list_verification_reports(*, ports, calculation_revision_id=None, operation)[source]

List VerificationReport records.

Optionally filtered to one CalculationRevision. The VerificationReportCatalogueRepositoryProtocol supplies the persisted report catalogue. Results are sorted by (calculation_revision_id, run_at).

Return type:

tuple[VerificationReport, ...]

Parameters:
get_verification_report(verification_report_id, *, ports, operation)[source]

Return one VerificationReport by id, or raise.

The optional VerificationReportCatalogueRepositoryProtocol supplies the persisted report catalogue for tests or alternate storage boundaries.

Return type:

VerificationReport

Parameters: