aeat.application.modelo._workflow_gate module¶

Workflow-gate support for modelo calculation revisions.

This module owns the adapter objects that let immutable calculation revisions participate in the filing workflow engine. The public application facade continues to export the operator-facing services from modelo.

The gate adapts one persisted CalculationRevision and its WorkUnit into WorkflowEngine inputs. It scopes deadline and filing-window checks with TaxpayerProfile, and locally approves filing drafts through the transient TransactionCatalogue used by the filing surface.

The gate is a precondition runner, not the owner of verification reports or filing records. _verification_actions invokes it with VERIFY after local verification findings have granted, while _filing_actions invokes it with FILE before local mark-as-filed persistence. Aborted workflow runs are persisted for audit and then surfaced as ModeloWorkflowGateError.

See also

_engine:: Owns deadline-independence for VERIFY and late-local FILE behavior.
_deadline_stage:: Selects the workflow obligation before submission preflight is reached.
SubmissionEngine:: Runs the read-only preflight gates using the deadline-window checker configured here.
DeadlineWindowChecker:: Protocol satisfied by the revision deadline-window adapter below.
_verification_actions:: Owns verification finding/report persistence around this gate.
_filing_actions:: Owns local filing-record persistence after this gate succeeds.

workflow_period_for_work_unit(work_unit)[source]¶

Return the canonical Period consumed by the workflow engine.

Quarterly work units use their registry token (for example "1T") but the deadline engine may declare a typed window period with a richer canonical shape. When the registry exposes such a deadline window, this helper returns that declared period so the workflow run addresses the same obligation the deadline engine will compute.

Return type:: Period
Parameters:: work_unit (WorkUnit)

build_revision_workflow_engine(*, revision, work_unit, profile, actor, clock, settings)[source]¶

Build and return a WorkflowEngine configured for one calculation revision.

The engine is wired with:

a deadline adapter over DeadlineEngine;
a revision-backed inputs provider that replays persisted calculation values;
a draft builder that validates and locally approves a registry draft;
a submission engine using the configured auth provider.

The returned engine does not persist verification reports or filing records; callers decide the WorkflowPurpose and perform state mutation only after run_revision_workflow_gate() returns successfully.

Parameters:

revision (CalculationRevision) – The immutable CalculationRevision whose persisted values are replayed into the workflow draft.
work_unit (WorkUnit) – The WorkUnit that supplies modelo, filing year, period, and bucket identity.
profile (TaxpayerProfile) – The TaxpayerProfile used for deadline and applicability scoping inside the workflow engine.
actor (str) – Operator label used when locally approving the transient draft.
clock (datetime) – Timestamp used for local draft approval metadata.
settings (Settings | None) – Optional runtime Settings; defaults to load_settings().

Return type:

WorkflowEngine

run_revision_workflow_gate(*, engine, profile, work_unit, today, runs_dir, run_repository, resumed_from=None, purpose=WorkflowPurpose.FILE)[source]¶

Run and persist the workflow gate for one modelo work unit and return a WorkflowResult.

purpose selects the workflow policy: VERIFY validates the calculation independently of the filing-window calendar, while FILE retains the local filing obligation gate and late-filing handling. Every result is saved through run_repository before the caller sees it. If the workflow aborts, the persisted result is raised as ModeloWorkflowGateError; no downstream verification or filing state should be written by the caller after that.

Return type:

WorkflowResult

Returns:

The successful WorkflowResult.

Parameters:

engine (WorkflowEngine) – The WorkflowEngine configured for the target revision.
profile (TaxpayerProfile) – The TaxpayerProfile used by the workflow run.
work_unit (WorkUnit) – The WorkUnit whose modelo and period select the workflow target.
today (date) – Reference date for deadline and preflight stages.
runs_dir (Path | None) – Optional filesystem location for persisted workflow runs.
run_repository (WorkflowRunRepository) – Repository that stores the resulting workflow run.
resumed_from (str | None) – Optional workflow run id when this execution resumes a prior run.
purpose (WorkflowPurpose) – Workflow policy to apply, usually VERIFY or FILE.