aeat.application.modelo._work_lifecycle module

Lifecycle mutations for modelo work units.

This module creates, lists, renames, and discards aeat.domain.modelos.WorkUnit records in the aeat.domain.modelos.WorkUnitCatalogueRepository. Each mutating action emits a typed event through BucketEventHistoryRepository, giving aeat.application.modelo.assemble_work_unit_history() a complete timeline from creation through discard.

The lifecycle layer mutates the work-unit catalogue only. It does not choose visible filing targets (see aeat.application.modelo._work_addressing), does not decide unsupported-modelo or applicability policy (see aeat.application.modelo._work_create_policy), and does not persist calculation revisions or filing records. Creation still performs the profile readiness and registry revision/period gates before inserting the work unit, so programmatic callers observe the same safety boundary as the CLI.

See also

aeat.application.modelo._work_addressing:

Resolves natural or exact operator targets before lifecycle mutation.

aeat.application.modelo.assemble_work_unit_history():

Reads the emitted bucket events into a chronological work-unit timeline.

CalculationRevision:

Defines calculation attempts and current/filed pointers under a work unit.

create_work_unit(*, bucket_id, modelo, filing_year, period, revision_id, name=None, actor='system', causante_ccaa=None, repository=None, bucket_event_repository=None, clock=None, enforce_applicability=True)[source]

Create or load the WorkUnit for an exact filing target key.

The key is bucket_id + modelo + filing_year + period + revision_id. The revision id must be known to the bundled registry and the period must be declared for that revision. The active profile must also be ready for the requested modelo work before any record is inserted.

If the derived work-unit id already exists, the existing record is returned without emitting another creation event. Otherwise a BORRADOR work unit is inserted and a MODELO_WORK_UNIT_CREATED bucket event is appended.

Return type:

WorkUnit

Parameters:
list_work_units(*, bucket_id=None, include_discarded=False, repository=None)[source]

Return WorkUnit records, optionally filtered to one bucket.

Discarded work units are hidden by default so operator-facing discovery sees only active draft roots. Pass include_discarded=True for audit/history views that need the abandoned records.

Return type:

tuple[WorkUnit, ...]

Parameters:
get_work_unit(work_unit_id, *, repository=None)[source]

Return one WorkUnit by id or raise WorkUnitNotFoundError.

Return type:

WorkUnit

Parameters:
rename_work_unit(work_unit_id, new_name, *, actor, repository=None, bucket_event_repository=None, clock=None)[source]

Update a WorkUnit display name and emit a rename event.

Discarded work units are immutable through this lifecycle surface; callers must create a fresh work unit for renewed work on the same filing target. Successful renames preserve the content-addressed work-unit id and update only display metadata plus updated_at.

Return type:

WorkUnit

Parameters:
discard_work_unit(work_unit_id, *, actor, reason=None, repository=None, bucket_event_repository=None, clock=None)[source]

Transition a WorkUnit to DESCARTADO and emit a discard event.

Discard is a durable state transition, not a physical delete. The work-unit record remains available for history/audit reads, repeated discards refuse with WorkUnitAlreadyDiscardedError, and active-listing callers must opt in with include_discarded=True to see the abandoned root.

Return type:

WorkUnit

Parameters: