cadrumo.application.workflow.protocols module

Protocol contracts for every component the workflow engine composes.

The composite workflow engine is defined against typing.Protocol surfaces — not concrete classes — for two reasons:

1. Cross-subpackage decoupling. Each Protocol lets the workflow engine integrate with an in-house subpackage without forcing a hard import dependency at the engine layer; adapters in application.workflow.adapters translate the richer real surfaces onto these narrow Protocols.

2. Protocol-shaped tests. Tests can supply narrow Protocol-conforming classes per scenario without importing the production adapters at the workflow layer.

Every Protocol here describes only the attributes the workflow engine actually reads. DeadlineEngineProtocol wraps the deadline engine’s compute method that returns a Schedule for a given TaxpayerProfile.

See also

WorkflowEngine

Orchestrates these contracts stage by stage.

application.workflow.adapters

Adapts production deadline, draft-building, submission, and live-read components to these contracts.

SubmissionEngine

Implements the read-only preflight surface described by SubmissionEngineProtocol.

WorkflowPurpose

Decides when workflow callers skip the AEAT filing-window preflight gate for local verification or local mark-as-filed paths.

class WorkflowFindingLike(*args, **kwargs)

Bases: Protocol

Narrow structural port over one registry-backed draft finding.

Wider than domain.submission.protocols.ModeloFindingLike, which declares only severity – the preflight gate reads severity alone and needs no code. Every finding a RegistryModeloDraftProtocol draft actually carries is a domain.filing.schema.ModeloValidationFinding, which declares both severity and code as required fields with no default. Typing RegistryModeloDraftProtocol.findings through this Protocol lets workflow-layer readers use finding.severity / finding.code directly instead of a getattr(..., None) guess – a field rename now fails loud instead of silently excluding every finding from whatever reads through it.

property severity: BaseSeverity

Return the severity that the workflow preflight should report.

property code: str

Return the stable registry code identifying this finding.

class DeadlineEngineProtocol(*args, **kwargs)

Bases: Protocol

Narrow surface over domain.deadlines.engine.DeadlineEngine.

compute(profile, year, *, today=None)

Return a Schedule for profile in year.

Parameters:

• profile (TaxpayerProfile) – The TaxpayerProfile whose filing obligations are scheduled.

• year (int) – The calendar year for which the schedule is computed.

• today (date | None) – Optional reference date for open-period classification.

Return type:

Schedule

class RegistryModeloDraftProtocol(*args, **kwargs)

Bases: ModeloDraftLike, Protocol

Workflow draft surface after registry-backed filing construction.

schema_version: str

property findings: tuple[WorkflowFindingLike, ...]

Return the validation findings the error-severity gate reads.

class ModeloDraftBuilderProtocol(*args, **kwargs)

Bases: Protocol

Narrow surface over application.filing.draft_construction.build_draft().

build(*, modelo, period, profile, inputs, fail_on_warning=False)

Build a registry-backed filing draft for the given TaxpayerProfile.

Returns a RegistryModeloDraftProtocol.

Return type:

RegistryModeloDraftProtocol

Parameters:

• modelo (str)

• period (Period)

• profile (TaxpayerProfile)

• inputs (ModeloInputs)

• fail_on_warning (bool)

class SubmissionEngineProtocol(*args, **kwargs)

Bases: Protocol

Read-only preflight surface over SubmissionEngine.

preflight(draft, *, today, skip_deadline_window=False, skip_auth_readiness=False)

Run preflight gates against draft; raise on failure.

skip_deadline_window skips the AEAT filing-window gate. The local workflow uses this for both WorkflowPurpose.VERIFY and WorkflowPurpose.FILE: VERIFY is calendar-independent, while FILE is a local mark-as-filed path whose obligation existence has already been enforced by the deadline stage.

skip_auth_readiness skips the auth-provider readiness gate. Both workflow purposes are local (the app never performs an actual AEAT submission), so auth is not required to complete the local build/verify/file/export flow; only live/AEAT-touching callers keep the gate enabled.

Return type:

None

Parameters:

• draft (RegistryModeloDraftProtocol)

• today (date)

• skip_deadline_window (bool)

• skip_auth_readiness (bool)

class CertificateBundleProtocol(*args, **kwargs)

Bases: Protocol

Narrow contract for the auth-provider probe used by workflow preflight.

The workflow engine calls describe() once during the preflight stage to prove the configured auth provider is present and healthy. Any exception raised here is translated into application.workflow.abort.WorkflowAbortReason.CERT_INVALID to preserve the existing workflow abort taxonomy.

describe()

Return the current auth-provider description; raise on failure.

Returns a core.auth_provider.AuthProviderDescription with the provider’s configured and available state.

Return type:

AuthProviderDescription

class ModeloInputsProviderProtocol(*args, **kwargs)

Bases: Protocol

Provides filing inputs for the draft stage.

Production adapters load inputs from bucket-scoped, secure application services rather than operator-supplied files.

load_inputs(*, modelo, period, profile)

Return the filing inputs for the draft build against the given TaxpayerProfile.

Return type:

TypeAliasType

Parameters:

• modelo (str)

• period (Period)

• profile (TaxpayerProfile)

class WorkflowExpedienteProtocol(*args, **kwargs)

Bases: Protocol

Narrow read surface for one AEAT expediente (open proceeding) entry.

An expediente is an administrative dossier AEAT associates with one modelo (e.g. "303") and one ejercicio (tax year). The workflow engine reads these two fields to decide whether an open proceeding blocks filing.

property modelo: str | None

Return the expediente’s modelo identifier, when declared.

property ejercicio: int | None

Return the expediente’s tax year, when declared.

class WorkflowNotificationProtocol(*args, **kwargs)

Bases: Protocol

Narrow read surface for one AEAT inbox notification entry.

The workflow engine reads tipo, leida, certificado_id, and concepto to decide whether an unread blocking notification (typically a requerimiento) should abort the current run.

property tipo: str

Return the AEAT notification type.

property leida: bool | None

Return whether the source marks this notification as read.

property certificado_id: str

Return the certificate identifier associated with the notification.

property concepto: str

Return the notification’s concept or subject.

class WorkflowNotificationsSnapshotProtocol(*args, **kwargs)

Bases: Protocol

Container protocol for a point-in-time AEAT inbox snapshot.

Wraps a sequence of WorkflowNotificationProtocol rows returned by the AEAT inbox adapter. The engine iterates rows once to find blocking requerimientos.

property rows: Sequence[WorkflowNotificationProtocol]

Return the notification rows contained in this snapshot.