cadrumo.application.modelo.work_lifecycle module

Lifecycle mutations for modelo work units.

This module creates, lists, renames, and discards WorkUnit records in the WorkUnitCatalogueRepositoryProtocol. Each mutating action emits a typed event through BucketEventHistoryRepositoryProtocol, giving cadrumo.application.modelo.history.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 cadrumo.application.modelo.work_addressing), does not decide unsupported-modelo or applicability policy (see cadrumo.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

cadrumo.application.modelo.work_addressing:

Resolves natural or exact operator targets before lifecycle mutation.

cadrumo.application.modelo.history.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.

class ActiveWorkUnitUse(*values)[source]

Bases: StrEnum

Application operations that require a mutable work-unit lifecycle state.

CALCULATE
IMPORT
class RevisionParentOperation(*values)[source]

Bases: StrEnum

Revision operations that require an active parent work unit.

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

Bases: BaseModel

Application-owned forward path for one observed work-unit lifecycle state.

The lifecycle service owns whether an observed work-unit state admits a concrete following action. The CLI only localizes this record and resolves its declared action through the live operator surface; it cannot choose a different action or manufacture a target argument.

Parameters:

data (Any)

notice_code: NamespacedId
summary_locale_key: NamespacedId
evidence: ConditionEvidence
action: ActionReference | None
argument_bindings: tuple[ActionArgumentBinding, ...]
no_recovery_outcome: NoRecoveryOutcome | None
lifecycle_continuation_for_work_list(work_units)[source]

Return the only honest continuation for a work-unit list observation.

Return type:

ModeloWorkLifecycleContinuation

Parameters:

work_units (Sequence[WorkUnit])

lifecycle_continuation_for_work_history(work_unit)[source]

Return the canonical state-inspection continuation for one history observation.

Return type:

ModeloWorkLifecycleContinuation

Parameters:

work_unit (WorkUnit)

lifecycle_continuation_for_work_status(work_unit)[source]

Return calculation only when the real calculation guard admits this unit.

Return type:

ModeloWorkLifecycleContinuation

Parameters:

work_unit (WorkUnit)

create_work_unit(*, bucket_id, modelo, filing_year, period, revision_id, name=None, actor='system', causante_ccaa=None, ports, operation, clock=None, enforce_applicability=True, profile=None)[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, the period must be declared for that revision, and the revision id must be the law-determined revision that law_selected_revision_for_work_target() would select for (modelo, filing_year, period) alone – this door re-confirms that pairing itself rather than trusting a caller to have resolved it, since a caller holding a stale or hand-picked revision id for the right modelo and a declared period would otherwise build a work unit under the wrong year’s norms with no signal. 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 and is still active, 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.

A DESCARTADO unit is REFUSED rather than returned. Because the id is content-addressed over exactly the coordinates this function is given, a retry after a discard re-derives the same id, so returning the record handed the caller a unit every downstream verb then reports as absent — stranding that filing target. The refusal states the dead end instead of restating the command that produced it. Recovery needs a supersede transition, which does not exist yet.

Return type:

WorkUnit

Parameters:
list_work_units(*, bucket_id=None, include_discarded=False, ports)[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:
require_active_work_unit(work_units, *, work_unit_id, repository_bucket_id, use)[source]

Resolve one scoped active work unit or raise its declared lifecycle refusal.

Calculation and external-import operations share this guard so a discarded state has one authority for addressability, typed facts, and the declared terminal verdict. Callers select only their operation identity; they cannot recreate the state predicate or its action/no-recovery outcome.

Return type:

WorkUnit

Parameters:
require_revision_parent_active(*, work_unit, calculation_revision_id, operation)[source]

Admit a verify/file revision only while its persisted parent work unit is active.

Return type:

WorkUnit

Parameters:
get_work_unit(work_unit_id, *, ports)[source]

Return one WorkUnit by id or raise WorkUnitNotFoundError.

Scoped to the repository’s own bucket: a unit belonging to another bucket is not addressable here and reads as not found.

Return type:

WorkUnit

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

Update a WorkUnit display name and emit a rename event.

Discarded work units are immutable through this lifecycle surface. Successful renames preserve the content-addressed work-unit id and update only display metadata plus updated_at.

Scoped to the repository’s own bucket: a unit belonging to another bucket is not addressable here, so an A-bound caller cannot rename a B unit and emit a B-scoped rename event.

Return type:

WorkUnit

Parameters:
discard_work_unit(work_unit_id, *, actor, reason=None, ports, 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.

Scoped to the repository’s own bucket: a unit belonging to another bucket is not addressable here, so an A-bound caller cannot discard a B unit and emit a B-scoped discard event.

Return type:

WorkUnit

Parameters: