cadrumo.application.workflow.run_models module

Strict run contracts for the composite workflow engine.

This module owns stages, purposes, deadline observations, step details, and terminal run results. Records are frozen strict Pydantic models or closed enumerations, and persisted presentation carries locale keys rather than rendered prose. Encrypted workflow state, declaration pointers, and active-profile helpers live in the separate _state_models owner.

See also

WorkflowEngine

Produces WorkflowResult records and advances WorkflowStage values.

WorkflowPurpose

Selects the local FILE or VERIFY policy that controls deadline and preflight treatment.

WorkflowRunRepository

Persists terminal WorkflowResult records in secure storage.

WorkflowStateRepository

Persists the encrypted WorkflowState envelope.

cadrumo.application.modelo.workflow_gate

Drives calculation revisions through the workflow and persists the resulting run record before verification or local filing state changes.

class WorkflowStage(*values)[source]

Bases: StrEnum

The read-only stages of the composite workflow, in strict order.

LOADING_PROFILE
COMPUTING_DEADLINES
CHECKING_INBOX
BUILDING_DRAFT
VALIDATING_DRAFT
RUNNING_PREFLIGHT
DONE
ABORTED
class WorkflowPurpose(*values)[source]

Bases: StrEnum

Why the workflow engine is being driven.

The purpose decides whether the filing-window deadline is an abort gate or merely informational context:

  • FILE — the end-to-end filing pipeline (work file and the end-to-end WorkflowEngine run). Filing without a pending obligation is refused: the COMPUTING_DEADLINES stage aborts with WorkflowAbortReason.NO_PENDING_OBLIGATION when the schedule carries no matching obligation and with WorkflowAbortReason.DEADLINE_PASSED when the obligation window has already closed.

  • VERIFY — the work verify calculation check. Verification asserts a calculation is internally sound against the registry’s verification expectations; it has no honest dependency on the AEAT filing calendar. The COMPUTING_DEADLINES stage records the filing-window state as informational context and never aborts on it, so a correct calculation can be confirmed early, offline, or for a past period.

FILE
VERIFY
class WorkflowSiteHealthFacts(**data)[source]

Bases: BaseModel

Locale-neutral persisted projection of one site-health observation.

Adapter evidence may include a probe URL, source-language marker text, and a redacted HTML fragment. Those transient diagnostics never cross the workflow-run persistence boundary. The projection retains only closed state, stable identity, timestamp, numeric status, retry timing, and count facts needed by renderers and operators.

Parameters:

data (Any)

alert_code: str
state: SiteHealthState
observed_at: AwareDatetime
http_status: int
retry_after_seconds: int | None
detected_marker_count: NonNegativeInt
classmethod from_status(status)[source]

Project adapter status without URL, marker text, or HTML evidence.

Return type:

WorkflowSiteHealthFacts

Parameters:

status (SiteHealthStatusLike)

class SiteHealthAlert(**data)[source]

Bases: BaseModel

Workflow-side alert carrying only stable site-health facts.

Attached to a WorkflowStep when the AEAT browser health-check adapter reports a non-nominal site status during a workflow run. stage identifies the workflow stage that observed the alert; run_id ties it to the enclosing WorkflowResult.

Parameters:

data (Any)

stage: WorkflowStage
status: WorkflowSiteHealthFacts
run_id: str
class WorkflowDeadlineRecoveryFacts(**data)[source]

Bases: BaseModel

Locale-neutral legal and amount facts for an overdue obligation.

The domain recovery record also carries an operator command. Workflow-run persistence deliberately excludes that presentation-owned string and keeps only registry identities and evaluated recargo facts.

Parameters:

data (Any)

still_filable: bool
recargo_band_id: str
min_completed_months: NonNegativeInt
max_completed_months: int | None
surcharge_pct: Decimal
interest_applies: bool
legal_ref: str
class WorkflowObligationFacts(**data)[source]

Bases: BaseModel

Strict persisted projection of one domain filing obligation.

ModeloDeadline contains source-language applicability prose and a raw recovery command. Neither belongs in a durable workflow record. This projection retains the canonical address, dates, status, legal identities, and typed overdue facts needed by resume and rendering consumers.

Parameters:

data (Any)

modelo: Modelo
period: Period
opens_on: date
closes_on: date
payment_cutoff_on: date | None
status: ObligationStatus
boe_references: tuple[str, ...]
recovery: WorkflowDeadlineRecoveryFacts | None
classmethod from_deadline(obligation)[source]

Project one domain deadline without its prose or raw command fields.

Return type:

WorkflowObligationFacts

Parameters:

obligation (ModeloDeadline)

class WorkflowDiagnosticSkipReason(*values)[source]

Bases: StrEnum

Closed reasons a non-applicable workflow diagnostic was skipped.

NOT_WIRED
class WorkflowDeadlineContextDetails(**data)[source]

Bases: _WorkflowStepDetail

The one of the closed deadline contexts a workflow step can carry.

Parameters:

data (Any)

kind: Literal['deadline_context']
modelo: Modelo
period: Period
opens_on: date | None
closes_on: date | None
filing_window: FilingWindowState | None
deadline_role: DeadlineRole | None
overdue: bool | None
extemporanea: bool | None
class WorkflowInboxSkippedDetails(**data)[source]

Bases: _WorkflowStepDetail

An inbox step intentionally skipped because its adapter is not wired.

Parameters:

data (Any)

kind: Literal['inbox_skipped']
skip_reason: Literal[WorkflowDiagnosticSkipReason.NOT_WIRED]
class WorkflowInboxBlockedDetails(**data)[source]

Bases: _WorkflowStepDetail

A workflow inbox failure with a bounded, machine-readable first item.

Parameters:

data (Any)

kind: Literal['inbox_blocked']
blocker_count: PositiveCount
first_notificacion_id: str
class WorkflowDraftBuiltDetails(**data)[source]

Bases: _WorkflowStepDetail

The durable identity of a successfully built draft.

Parameters:

data (Any)

kind: Literal['draft_built']
draft_id: str
class WorkflowAlreadyFiledDetails(**data)[source]

Bases: _WorkflowStepDetail

The model and period already evidenced as filed.

Parameters:

data (Any)

kind: Literal['already_filed']
modelo: Modelo
period: Period
expediente_count: PositiveCount
class WorkflowDraftNotReadyDetails(**data)[source]

Bases: _WorkflowStepDetail

A built draft whose lifecycle status does not permit filing.

Parameters:

data (Any)

kind: Literal['draft_not_ready']
draft_id: str
draft_status: ModeloDraftStatus
blocking_finding_codes: tuple[str, ...]
class WorkflowDraftMismatchDetails(**data)[source]

Bases: _WorkflowStepDetail

A draft that cannot be used for the target obligation.

The mismatching facts themselves are condition evidence on the paired PreconditionVerdict, not a second free-form detail map.

Parameters:

data (Any)

kind: Literal['draft_mismatch']
draft_id: str
class WorkflowValidationFailedDetails(**data)[source]

Bases: _WorkflowStepDetail

The number of blocking validation findings on one draft.

Parameters:

data (Any)

kind: Literal['validation_failed']
error_count: PositiveCount
class WorkflowAuthCheckDetails(**data)[source]

Bases: _WorkflowStepDetail

Closed certificate/provider readiness facts for preflight.

Parameters:

data (Any)

kind: Literal['auth_check']
provider_kind: AuthProviderKind | None
provider_check_skipped: bool
skip_reason: Literal[WorkflowDiagnosticSkipReason.NOT_WIRED] | None
cert_not_after: date | None
cert_severity: CertificateSeverityValue | None
cert_days_until_expiry: int | None
class WorkflowPreflightFailedDetails(**data)[source]

Bases: _WorkflowStepDetail

A preflight failure identified by a stable application error code.

Parameters:

data (Any)

kind: Literal['preflight_failed']
error_code: NamespacedId
auth_check: WorkflowAuthCheckDetails | None
class WorkflowFailureDetails(**data)[source]

Bases: _WorkflowStepDetail

A non-precondition workflow failure represented without exception prose.

Parameters:

data (Any)

kind: Literal['workflow_failure']
error_code: NamespacedId
WORKFLOW_SUMMARY_LOCALE_KEYS: tuple[str, ...]

Every persisted workflow summary locale identity emitted by engine producers.

The _LOCALE_KEYS suffix makes this closed producer set visible to the static locale scanner even though a persisted result selects one key at runtime. Keep it synchronized with the workflow engine, deadline stage, and recording failure producers.

class WorkflowStep(**data)[source]

Bases: BaseModel

A single step in a WorkflowResult.

Parameters:

data (Any)

stage: WorkflowStage
started_at: datetime
ended_at: datetime | None
success: bool | None
summary_locale_key: WorkflowLocaleKey
details: WorkflowStepDetails | None
precondition_verdict: PreconditionVerdict | None
site_health_alert: SiteHealthAlert | None
class WorkflowResult(**data)[source]

Bases: BaseModel

The full result of one WorkflowEngine.run_next() invocation.

Parameters:

data (Any)

run_id: str
started_at: datetime
ended_at: datetime
final_stage: WorkflowStage
aborted_reason: WorkflowAbortReason | None
obligation: WorkflowObligationFacts | None
draft_id: str | None
submission_id: str | None
steps: tuple[WorkflowStep, ...]
summary_locale_key: WorkflowLocaleKey
summary_details: WorkflowStepDetails | None
resumed_from: str | None
compute_run_id(*, tax_id, modelo, period, started_at)[source]

Return a stable 16-char hex hash for a workflow run.

Return type:

str

Parameters: