cadrumo.domain.modelos.work_unit module

Modelo work-unit value records.

WorkUnit and WorkUnitCatalogue bind a ModeloCode, Period, BucketId, and WorkUnitId into the operator-facing handle addressed by derive_work_unit_id().

A modelo work unit is a stable, bucket-scoped handle over one calculation revision of a specific (modelo, year, period). It is the operator-facing object the modelo workflow verbs (calculate, verify, file, filing-record, etc.) attach state to. The work unit itself carries metadata only — its calculation results, verification reports, and filing records live in separate stores keyed by work_unit_id.

The work-unit identifier is a SHA-256 hex digest derived deterministically from the four-axis key (bucket_id, modelo, filing_year, period, revision_id). The deterministic derivation means two consumers of the same four-axis key see the same work_unit_id without round-tripping through storage. Renaming a work unit does not change the identifier; name is a display-only attribute.

class WorkUnitState(*values)[source]

Bases: StrEnum

Closed enumeration of work-unit lifecycle states.

  • BORRADOR — default state at creation. The work unit participates in default listings and accepts mutation (rename, future calculation revisions).

  • DESCARTADO — operator marked the work unit abandoned. Excluded from default listings; mutations are rejected. Revision payloads remain in storage for audit; the work unit cannot be re-activated.

BORRADOR
DESCARTADO
derive_work_unit_id(*, bucket_id, modelo, filing_year, period, revision_id)[source]

Return the deterministic work_unit_id for a four-axis key.

The five inputs are normalised (stripped, upper-cased where case is insignificant) into a keyed payload and hashed through content_hash_hex(), the project’s one content-addressing primitive, yielding 64-character lowercase hex.

This derivation previously joined the components with a separator byte and called sha256_hex() directly, while this docstring claimed it was “identical to the catalogue-key shape the project uses elsewhere”. It was not: every other derived id in the tree hashes canonical JSON through content_hash_hex. Routing this one onto that primitive makes the claim true and leaves one content-addressing mechanism rather than two.

Determinism is the operative contract: callers that build the same four-axis key see the same identifier without round-tripping through storage.

Return type:

str

Parameters:

  • bucket_id (str)

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • revision_id (RevisionId)

class WorkUnit(**data)[source]

Bases: BaseModel

One operator-facing modelo calculation work unit.

Variables:

  • work_unit_id – Lowercase 64-char SHA-256 derived from (bucket_id, modelo, filing_year, period, revision_id) by derive_work_unit_id(). The identifier is stable across renames.

  • bucket_id – Stable bucket identity the work unit lives inside. Two work units with the same modelo / year / period / revision in different buckets have different work_unit_id values.

  • modelo – AEAT modelo code (e.g. "303", "130").

  • filing_year – Tax year for which the modelo is being filed.

  • period – Typed filing period value carrying the filing year and bare registry token (e.g. "4T", "0A", "01").

  • revision_id – Stable id of the registry-known modelo revision the work unit targets.

  • name – Display name. Defaults to "<modelo>-<year>-<period>" when the operator does not supply one explicitly.

  • created_at – Timezone-aware UTC timestamp at first creation.

  • updated_at – Timezone-aware UTC timestamp at the most recent mutation. Equals created_at on a fresh work unit.

  • state – Lifecycle state — BORRADOR by default, DESCARTADO once the operator marks the unit abandoned via the discard verb.

  • discarded_at – Timezone-aware UTC timestamp set at discard time. None for non-discarded units.

  • discarded_by – Actor label captured at discard time. None for non-discarded units.

  • discard_reason – Operator-supplied free-text reason for the discard. None when no reason was given (or when the unit is not discarded).

Parameters:

data (Any)

work_unit_id: WorkUnitId
bucket_id: BucketId
modelo: ModeloCode
filing_year: FilingYear
period: Period
revision_id: _RevisionId
name: _DisplayName
created_at: UtcInstant
updated_at: UtcInstant
state: WorkUnitState
discarded_at: UtcInstant | None
discarded_by: ModeloActorLabel | None
discard_reason: OperatorReason | None
current_calculation_revision_id: Hex64Str | None
filed_calculation_revision_id: Hex64Str | None
current_filing_record_id: Hex64Str | None
causante_ccaa: CCAA | None
class WorkUnitCatalogue(**data)[source]

Bases: BaseModel

Immutable catalogue of every work unit known in storage.

The catalogue is a frozen mapping keyed by work_unit_id. Lookups by other shapes (bucket, modelo, year, period) are iterated at the catalogue boundary; the catalogue itself does not index secondary keys.

Parameters:

data (Any)

work_units: Mapping[str, WorkUnit]
get(work_unit_id)[source]

Return the work unit for work_unit_id or None if absent.

Return type:

WorkUnit | None

Returns:

The WorkUnit for the given id, or None when not found.

Parameters:

work_unit_id (str)

values()[source]

Return a view of every WorkUnit in the catalogue.

Return type:

ValuesView[WorkUnit]