cadrumo.application.modelo.workflow_gate module

Workflow-gate support for modelo calculation revisions.

This module owns the application orchestration that lets immutable calculation revisions participate in the filing workflow engine. Persistence capabilities arrive through WorkflowGatePorts; their concrete adapters are composed outside the application layer. 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.

WorkflowGatePorts:

Required application-owned persistence capabilities for this gate.

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_deadline_window_checker(*, profile, engine)[source]

Build the revision filing-window checker for one taxpayer.

The returned DeadlineWindowChecker binds the supplied TaxpayerProfile and DeadlineEngine. It answers raw, inclusive window membership for an exact modelo and period; workflow purpose and skip policy remain owned by the workflow engine.

Parameters:

  • profile (TaxpayerProfile) – Taxpayer facts used to compute the obligation schedule.

  • engine (DeadlineEngine) – Registry-backed deadline engine used for that schedule.

Return type:

DeadlineWindowChecker

Returns:

The production deadline-window checker bound to profile.

build_revision_workflow_engine(*, certificate_secret_backend_factory, operator_scope_ports, revision, work_unit, profile, actor, clock, settings, draft_review_ports, workflow_gate_ports, operation)[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:

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

  • operator_scope_ports (OperatorScopePorts) – Operator-scope capabilities supplied to the authentication provider.

  • 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().

  • draft_review_ports (DraftReviewPorts) – Required application-owned capabilities used to approve the transient filing draft.

  • workflow_gate_ports (WorkflowGatePorts) – Required application-owned draft persistence and submission-history capabilities.

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

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 (WorkflowRunRepositoryProtocol) – 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.