aeat.application.workflow._resume module¶

Workflow-resumption preconditions and context assembly.

Loads a prior application.workflow.WorkflowResult by run_id and decides whether the operator may start a fresh attempt against the same (modelo, period) axis. Returns a application.workflow.WorkflowResumeContext the caller hands to application.workflow.WorkflowEngine.run_for_period() to drive the new attempt.

The action is pure-local: no AEAT contact, no live read or write, no mutation of the prior run record. Resuming a workflow is the operator asking the local orchestrator to retry; whether that retry then contacts AEAT depends on the engine, not on this action.

This module uses application.workflow.WorkflowResult, application.workflow.WorkflowEngine, and domain.deadlines.ModeloDeadline for workflow resumption logic.

See also

application.workflow.WorkflowResult: Persisted terminal run record inspected before any resume context is returned.
application.workflow.WorkflowRunRepository: Secure run-history repository behind application.workflow.load_run() and application.workflow.list_runs().
application.workflow.WorkflowEngine: Fresh attempt executor that consumes application.workflow.WorkflowResumeContext through run_for_period(resumed_from=...).
application.modelo: Owns visible modelo work addressing, revision selection, and conversion from registry filing periods to workflow periods.
entrypoints.cli._modelo_work_runs_cli: CLI surface that resolves operator resume selectors and emits application.workflow.WorkflowResumeTargetResolution metadata.

Resumability rules:

the prior result MUST carry final_stage = ABORTED — DONE results are already filed and cannot be retried; in-progress results are not surfaced through application.workflow.load_run() and so cannot reach this path.

the prior result’s aborted_reason MUST NOT be terminal-by- design (NO_PENDING_OBLIGATION, ALREADY_FILED, USER_CANCELLED). Those abort reasons describe states where retrying would not produce a different outcome.

the prior result MUST carry an obligation — without it we cannot enumerate the (modelo, period) to retry against.

exception WorkflowResumeRefusedError(message=None, *, context=None, suggestion=None, translated_message=None)[source]¶

Bases: WorkflowError

Raised when a prior application.workflow.WorkflowResult cannot be resumed.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
suggestion (str | None)
translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]¶

exception WorkflowResumeRunAmbiguousError(*, modelo, period, candidates)[source]¶

Bases: WorkflowError

Raised when natural-key resume matches more than one workflow run.

Parameters:

modelo (str)
period (Period)
candidates (tuple[WorkflowResumeRunCandidate, ...])

Return type:

None

code: ClassVar[ErrorCode]¶

class WorkflowResumeRunCandidate(**data)[source]¶

Bases: BaseModel

Operator-facing workflow run candidate for natural-key resume guidance.

Parameters:

run_id (str)
modelo (str)
period (Period)
final_stage (str)
aborted_reason (str | None)
started_at (datetime)
short_work_unit_id (str | None)
work_unit_id (str | None)

run_id: str¶

modelo: str¶

period: Period¶

final_stage: str¶

aborted_reason: str | None¶

started_at: datetime¶

short_work_unit_id: str | None¶

work_unit_id: str | None¶

class WorkflowResumeTargetResolution(**data)[source]¶

Bases: BaseModel

Resolved workflow-run target plus visible modelo work metadata.

Carries the WorkflowResult.run_id value selected by direct run id, work-unit id, calculation-revision id, or visible modelo filing selector. Visible and exact modelo targets are resolved through application.modelo.ModeloVisibleFilingTarget and application.modelo.ModeloExactWorkUnitTarget before workflow run lookup.

Parameters:

run_id (str)
source (str)
modelo (str | None)
period (Period | None)
filing_year (int | None)
work_unit_id (str | None)
short_work_unit_id (str | None)
calculation_revision_id (str | None)
short_calculation_revision_id (str | None)

run_id: str¶

source: str¶

modelo: str | None¶

period: Period | None¶

filing_year: int | None¶

work_unit_id: str | None¶

short_work_unit_id: str | None¶

calculation_revision_id: str | None¶

short_calculation_revision_id: str | None¶

class WorkflowResumeContext(**data)[source]¶

Bases: BaseModel

Inputs the engine needs to start a fresh attempt over a prior run.

Produced from a resumable application.workflow.WorkflowResult and passed to application.workflow.WorkflowEngine.run_for_period() by callers that launch the retry.

Parameters:

resumed_from_run_id (str)
modelo (str)
period (Period)
obligation (ModeloDeadline)
aborted_reason (WorkflowAbortReason)

resumed_from_run_id: str¶

modelo: str¶

period: Period¶

obligation: ModeloDeadline¶

aborted_reason: WorkflowAbortReason¶

resume_modelo_workflow(run_id)[source]¶

Validate that run_id may be resumed and return a fresh-attempt context.

The caller is expected to drive application.workflow.WorkflowEngine.run_for_period() with modelo=context.modelo and period=context.period to produce a fresh application.workflow.WorkflowResult.

Parameters:: run_id (str) – The 16-character hex run id of the prior aborted workflow run to resume.
Return type:: WorkflowResumeContext
Returns:: A application.workflow.WorkflowResumeContext carrying the modelo, period, obligation, and aborted reason for the prior run.
Raises:: WorkflowResumeRefusedError – When the prior run is not in ABORTED state, was aborted for a non-resumable reason, or lacks an obligation.

resolve_modelo_workflow_resume_target(*, target=None, workflow_run_id=None, work_unit_id=None, calculation_revision_id=None, modelo=None, year=None, period=None, registry_revision_id=None, bucket_id=None, selector=None)[source]¶

Resolve the operator’s resume address and return a target resolution.

Exact run ids remain the direct path. Work-unit ids, calculation-revision ids, and visible modelo/year/period selectors resolve through the public modelo addressing facade before workflow run lookup, so this service does not duplicate modelo selector policy.

Return type:

WorkflowResumeTargetResolution

Returns:

A application.workflow.WorkflowResumeTargetResolution carrying the selected run id and any resolved modelo work metadata.

Parameters:

target (str | None)
workflow_run_id (str | None)
work_unit_id (str | None)
calculation_revision_id (str | None)
modelo (str | None)
year (int | None)
period (Period | None)
registry_revision_id (str | None)
bucket_id (str | None)
selector (object | None)

find_latest_run_for_period(*, modelo, period)[source]¶

Return the most recent persisted workflow run for (modelo, period).

A workflow run id is a 16-character hash an operator cannot derive by hand, so a caller that only knows the (modelo, period) of a work unit needs a way to resolve the run id. This helper scans the persisted run history and returns the newest run whose resolved obligation matches the supplied (modelo, period).

The returned run is not gated for resumability — pass its run_id to application.workflow.resume_modelo_workflow(), which applies the resumability rules and produces a precise refusal if the latest run cannot be retried.

Parameters:

modelo (str) – Target modelo identifier.
period (Period) – Target typed workflow period.

Return type:

WorkflowResult

Returns:

The newest matching application.workflow.WorkflowResult.

Raises:

WorkflowError – When no persisted run targets (modelo, period).

find_unique_run_for_period(*, modelo, period, work_unit_id=None, short_work_unit_id=None)[source]¶

Return a workflow run for (modelo, period) or refuse ambiguity.

Natural-key resume is an operator-facing lookup. If more than one persisted run exists for the same workflow period, the caller must choose an exact run id instead of guessing which attempt to resume.

Return type:

WorkflowResult

Returns:

The unique matching application.workflow.WorkflowResult.

Parameters:

modelo (str)
period (Period)
work_unit_id (str | None)
short_work_unit_id (str | None)

resolve_modelo_workflow_run_for_resume(target, *, source='modelo_work_target')[source]¶

Resolve a modelo work target to a resume target resolution.

The modelo application facade remains the owner of visible filing target lookup and registry-period to workflow-period conversion. Natural-key targets require exactly one persisted workflow run for that period; exact work-unit targets select the newest run for the resolved workflow period.

Return type:

WorkflowResumeTargetResolution

Returns:

A application.workflow.WorkflowResumeTargetResolution suitable for passing to application.workflow.resume_modelo_workflow().

Parameters:

target (ModeloWorkTarget)
source (str)

resolve_modelo_visible_workflow_run_for_resume(*, modelo, filing_year, period, registry_revision_id=None, bucket_id=None)[source]¶

Resolve natural modelo filing selectors to a resume target resolution.

The selector is represented as a application.modelo.ModeloVisibleFilingTarget before delegation to the shared modelo addressing facade.

Return type:

WorkflowResumeTargetResolution

Returns:

A WorkflowResumeTargetResolution for the visible filing target.

Parameters:

modelo (str)
filing_year (int)
period (Period)
registry_revision_id (str | None)
bucket_id (str | None)

resolve_modelo_exact_workflow_run_for_resume(*, work_unit_id, bucket_id=None)[source]¶

Resolve an exact work-unit id to a resume target resolution.

Exact work-unit ids are represented as application.modelo.ModeloExactWorkUnitTarget values before workflow run lookup.

Return type:

WorkflowResumeTargetResolution

Returns:

A WorkflowResumeTargetResolution for the exact work-unit id.

Parameters:

work_unit_id (str)
bucket_id (str | None)

workflow_resume_candidate_lines(candidates)[source]¶

Return tabular candidate guidance for ambiguous natural-key resume.

Parameters:: candidates (tuple[WorkflowResumeRunCandidate, ...]) – WorkflowResumeRunCandidate rows collected from the ambiguous workflow-period lookup.
Return type:: str