cadrumo.application.modelo.work_addressing module

Application-level addressing for modelo work commands.

The address facade converts visible modelo/year/period filing targets and exact work-unit ids into ModeloWorkAddress values, resolves them through the central selector contract, and returns the matching WorkUnit or CalculationRevision.

This module is the application facade over the accepted addressing policy: operators address the active bucket/profile plus modelo, filing year, and period; raw ids remain advanced exact-addressing escape hatches. Ambiguous visible targets, contradictory exact-id plus natural-key flags, and discarded natural-key matches are handled by the captured-catalogue operation in this defining module rather than by CLI-local string logic.

Creation flows validate the law-determined registry revision before delegating to create_work_unit(); an explicit --revision is an assertion of the selected legal revision, not a free override. Revision flows apply ModeloCalculationRevisionSelector defaults so verify, file, and export commands consume only the lifecycle states they are allowed to handle.

See also

select_modelo_work_resolution():

The authoritative pure work selector over one captured catalogue.

_modelo:

CLI commands that project operator flags into this facade.

exception ModeloWorkSelectorError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloError

Base error for Modelo work-selection refusals.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkNoActiveBucketError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError

Raised when an implicit selector cannot capture an active bucket.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkUnitNotFoundError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError

Raised when an exact work identifier resolves no all-state unit.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkSelectorContradictionError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError

Raised when an exact selector contradicts supplied coordinates.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkVisibleTargetAmbiguousError(candidates, *, selector=None)[source]

Bases: ModeloWorkSelectorError

Raised after the deterministic complete candidate set has cardinality > 1.

Parameters:
Return type:

None

code
exception ModeloWorkRevisionConflictError(*, requested_revision_id, existing)[source]

Bases: ModeloWorkSelectorError

Raised only after a singleton natural candidate fails its revision assertion.

Parameters:
Return type:

None

code
exception ModeloRevisionPickError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloError

Raised when a calculation-revision selector is internally inconsistent.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class ModeloVisibleFilingTarget(modelo, filing_year, period, registry_revision_id=None, bucket_id=None)[source]

Bases: object

Operator-visible modelo filing target under one bucket/profile.

This is the normal user-facing address: bucket/profile plus modelo, filing year, and period, with an optional registry-revision assertion for disambiguation.

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (RevisionId | None)

  • bucket_id (str | None)

modelo: str
filing_year: int
period: Period
registry_revision_id: TypeAliasType | None
bucket_id: str | None
to_work_address()[source]

Project the visible target into the shared ModeloWorkAddress shape.

Return type:

ModeloWorkAddress

class ModeloExactWorkUnitTarget(work_unit_id, bucket_id=None)[source]

Bases: object

Advanced exact-addressing target for one content-addressed work unit.

Use this only when the caller already has an authoritative WorkUnitId; visible filing targets remain the default operator path.

Parameters:

  • work_unit_id (WorkUnitId)

  • bucket_id (str | None)

work_unit_id: TypeAliasType
bucket_id: str | None
to_work_address()[source]

Project the exact target into the shared ModeloWorkAddress shape.

Return type:

ModeloWorkAddress

class ModeloRevisionPick(selector=ModeloCalculationRevisionSelector.CURRENT, calculation_revision_id=None, default_for=None)[source]

Bases: object

Command-specific calculation-revision pick under a resolved work target.

default_for applies the command policy owned by selectors: verify selects a draft, file selects a verified-complete revision, and export prefers the current filed revision before falling back to an unambiguous verified revision.

Parameters:
selector: ModeloCalculationRevisionSelector
calculation_revision_id: TypeAliasType | None
default_for: TypeAliasType | None
classmethod explicit(calculation_revision_id)[source]

Create an exact calculation-revision ModeloRevisionPick.

Return type:

ModeloRevisionPick

Parameters:

calculation_revision_id (CalculationRevisionId)

class ModeloResolvedWorkProjection(work_unit_id, short_work_unit_id, bucket_id, modelo, filing_year, period, registry_revision_id, state, current_calculation_revision_id, filed_calculation_revision_id, current_filing_record_id, created_at, updated_at)[source]

Bases: object

Support-safe projection of a resolved modelo work target.

The projection exposes the visible filing coordinates plus short ids for support guidance without making raw ids the normal operator workflow.

Parameters:

  • work_unit_id (WorkUnitId)

  • short_work_unit_id (str)

  • bucket_id (str)

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (RevisionId)

  • state (str)

  • current_calculation_revision_id (CalculationRevisionId | None)

  • filed_calculation_revision_id (CalculationRevisionId | None)

  • current_filing_record_id (str | None)

  • created_at (str)

  • updated_at (str)

work_unit_id: TypeAliasType
short_work_unit_id: str
bucket_id: str
modelo: str
filing_year: int
period: Period
registry_revision_id: TypeAliasType
state: str
current_calculation_revision_id: TypeAliasType | None
filed_calculation_revision_id: TypeAliasType | None
current_filing_record_id: str | None
created_at: str
updated_at: str
classmethod from_work_unit(work_unit)[source]

Project a Cadrumo work unit into a resolved-work projection.

Converts WorkUnit into ModeloResolvedWorkProjection.

Return type:

ModeloResolvedWorkProjection

Parameters:

work_unit (WorkUnit)

class ModeloResolvedRevisionProjection(calculation_revision_id, short_calculation_revision_id, work_unit_id, short_work_unit_id, selector, state, created_at, updated_at, verified_at=None, filed_at=None)[source]

Bases: object

Support-safe projection of a resolved calculation revision.

Carries the selected revision, selector policy, lifecycle state, and short ids used by CLI guidance after a work target has been resolved.

Parameters:

  • calculation_revision_id (CalculationRevisionId)

  • short_calculation_revision_id (str)

  • work_unit_id (WorkUnitId)

  • short_work_unit_id (str)

  • selector (ModeloCalculationRevisionSelector)

  • state (str)

  • created_at (str)

  • updated_at (str)

  • verified_at (str | None)

  • filed_at (str | None)

calculation_revision_id: TypeAliasType
short_calculation_revision_id: str
work_unit_id: TypeAliasType
short_work_unit_id: str
selector: ModeloCalculationRevisionSelector
state: str
created_at: str
updated_at: str
verified_at: str | None
filed_at: str | None
classmethod from_revision(revision, *, selector)[source]

Project a CalculationRevision into a ModeloResolvedRevisionProjection.

Return type:

ModeloResolvedRevisionProjection

Parameters:
class ModeloWorkAddress(work_unit_id=None, operator_work_unit_id=None, modelo=None, filing_year=None, period=None, registry_revision_id=None, bucket_id=None)[source]

Bases: object

Operator-facing or exact modelo work address.

This is the shared transport shape consumed at the application facade boundary. Prefer ModeloVisibleFilingTarget for model/year/period addressing or ModeloExactWorkUnitTarget for the advanced exact-id escape hatch, then project into this shape before selector resolution.

Parameters:

  • work_unit_id (WorkUnitId | None)

  • operator_work_unit_id (str | None)

  • modelo (str | None)

  • filing_year (int | None)

  • period (Period | None)

  • registry_revision_id (RevisionId | None)

  • bucket_id (str | None)

work_unit_id: TypeAliasType | None
operator_work_unit_id: str | None
modelo: str | None
filing_year: int | None
period: Period | None
registry_revision_id: TypeAliasType | None
bucket_id: str | None
exception ModeloWorkAddressNotFoundError(message=None, *, context=None, translated_message=None, precondition_failure=None)[source]

Bases: ModeloPreconditionErrorMixin, ModeloError

Raised when a natural modelo work address resolves no work unit.

Parameters:
Return type:

None

code
exception ModeloWorkRegistryYearMismatchError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloError

Raised when an explicit revision diverges from the law-determined one.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkPeriodTokenError(*, year, token, modelo, declared_tokens)[source]

Bases: ModeloError

Raised when an operator-facing period token cannot be normalized.

Parameters:
Return type:

None

code
class ModeloWorkEnsureResult(work_unit, reused, name_applied=None)[source]

Bases: object

Result of resolving or creating a visible-target work unit.

Parameters:
work_unit: WorkUnit
reused: bool
name_applied: str | None
work_address_for_modelo_target(target)[source]

Coerce a typed modelo work target into a ModeloWorkAddress selector shape.

Return type:

ModeloWorkAddress

Parameters:

target (ModeloWorkTarget)

modelo_work_address_from_operator_target(*, work_unit_id, modelo, year, period, registry_revision_id, bucket_id=None)[source]

Build a ModeloWorkAddress from exact or visible operator input.

A complete visible target is modelo + year + typed Period. If no visible target is supplied, an exact work_unit_id is required. Period year mismatches fail here before the selector sees the request.

Return type:

ModeloWorkAddress

Parameters:

  • work_unit_id (str | None)

  • modelo (str | None)

  • year (int | None)

  • period (Period | None)

  • registry_revision_id (RevisionId | None)

  • bucket_id (str | None)

resolve_modelo_work_unit_for_operator_target(*, work_unit_id=None, modelo=None, year=None, period=None, registry_revision_id=None, bucket_id=None, catalogue, resolved_bucket_id)[source]

Resolve exact or visible operator input to one active WorkUnit.

The result comes from the shared selector boundary, so ambiguity and exact-id/natural-key contradictions surface as typed selector errors.

Return type:

WorkUnit

Parameters:

  • work_unit_id (str | None)

  • modelo (str | None)

  • year (int | None)

  • period (Period | None)

  • registry_revision_id (RevisionId | None)

  • bucket_id (str | None)

  • catalogue (WorkUnitCatalogue)

  • resolved_bucket_id (str)

resolve_modelo_revision_for_operator_target(*, calculation_revision_id, work_unit_id, modelo, year, period, registry_revision_id, bucket_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, default_for=None, catalogue, resolved_bucket_id, ports)[source]

Resolve one CalculationRevision from exact or visible operator input.

An explicit calculation-revision id can stand alone as the exact escape hatch. Otherwise the work target is resolved first and the selector/default policy is applied under that work unit.

Return type:

CalculationRevision

Parameters:
resolve_modelo_work_target(target, *, catalogue, bucket_id)[source]

Resolve any supported modelo target through the shared selector boundary.

Returns a ModeloWorkResolution containing the resolved work unit or typed absence/ambiguity metadata from this defining module’s pure selector.

Return type:

ModeloWorkResolution

Parameters:
project_modelo_work_unit(work_unit)[source]

Project an internal work unit into the visible ModeloResolvedWorkProjection addressing contract.

Return type:

ModeloResolvedWorkProjection

Parameters:

work_unit (WorkUnit)

diverging_work_target_revision_axes(*, law_revision_id, requested_revision_id, stored_revision_id)[source]

Return the axis names whose asserted revision is not the law-determined one.

The one comparison behind both revision-assertion surfaces. An axis that supplies no value asserts nothing and can never diverge; a supplied value is normalised and judged against the law-determined revision ALONE, never against the other axis, so a stored value can never select the revision a request is judged by.

Extracted because the rule was written twice, in two dispositions – this module raising on divergence and the Workspace projection recording it as typed data. The dispositions differ legitimately: an exception escaping a read projection would destroy the information its typed refusal exists to carry. The COMPARISON differing would not be legitimate, and two copies of one normalisation drift silently: a change to what counts as equal lands at one site, the other goes on answering the old question, and the two surfaces disagree about whether a taxpayer’s stored revision matches the law.

Return type:

frozenset[str]

Returns:

The diverging axis names, empty when every supplied axis matches.

Parameters:

  • law_revision_id (RevisionId)

  • requested_revision_id (RevisionId | None)

  • stored_revision_id (RevisionId | None)

assert_work_target_revision(capture, *, requested_revision_id, stored_revision_id)[source]

Assert both work-target revision axes against one law-selected capture.

capture carries the single law-determined projection for the visible filing target. The requested axis is an operator --revision assertion; the stored axis is the revision already recorded on a work unit. The axes are independent: either may be absent, and each is checked against the same captured law-determined revision rather than against the other, so a stored value can never select the revision a request is judged by.

Return type:

TypeAliasType

Returns:

The law-determined revision id carried by capture.

Raises:

ModeloWorkRegistryYearMismatchError – An supplied axis diverges from the law-determined revision.

Parameters:
law_selected_revision_for_work_target(*, modelo, filing_year, period, requested_revision_id=None, stored_revision_id=None, operation)[source]

Capture the law-selected revision once and assert every supplied axis.

Exactly one RegistryAuthorityCapture is taken for (modelo, filing_year, period), so the work path performs one registry read and both axes are judged against the same atomic projection. Only the selected revision’s identity is read, so the capture asks for the lowest authority rung: a work unit may target a revision that declares less than filing grade, and the filing-grade gates refuse it later where they apply.

Return type:

TypeAliasType

Parameters:
exception ModeloWorkCaptureError(message=None, *, context=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError

Raised when a work capture cannot reach one uncontended observation.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class ModeloWorkCapture(resolution, comparison_domain, generation)[source]

Bases: object

One isolated work resolution and its currentness coordinate.

The capture carries the strict frozen ModeloWorkResolution selected over exactly one catalogue read, plus an opaque comparison domain and a generation. The physical storage root, bucket, namespace and object key that produced it are folded into the domain digest and are never exposed.

Parameters:
resolution: ModeloWorkResolution
comparison_domain: str
generation: int
require_current(current)[source]

Refuse a currentness comparison outside this physical process domain.

Return type:

ModeloWorkCapture

Parameters:

current (ModeloWorkCurrentCoordinate)

class ModeloWorkCurrentCoordinate(comparison_domain, generation)[source]

Bases: object

Opaque same-process coordinate for one work catalogue owner scope.

Parameters:

  • comparison_domain (str)

  • generation (int)

comparison_domain: str
generation: int
require_current(captured)[source]

Require a capture from this exact scope and process incarnation.

Return type:

ModeloWorkCurrentCoordinate

Parameters:

captured (ModeloWorkCapture)

capture_modelo_work_resolution(request, *, catalogue_repository, mode=ModeloWorkSelectionMode.VISIBLE_OR_EXACT)[source]

Atomically capture one work resolution over a single catalogue read.

The implicit pointer limb and the one-record catalogue coordinate are read so that a pointer replacement interleaved with the catalogue read is retried rather than composed, which is what defeats a pointer/catalogue ABA. An explicit bucket_id excludes the pointer limb entirely while still carrying the catalogue generation. No registry is consulted and the catalogue is read exactly once per successful attempt.

Return type:

ModeloWorkCapture

Parameters:
ensure_modelo_work_unit_for_active_target(*, bucket_id, modelo, filing_year, period, registry_revision_id, name=None, actor='operator', causante_ccaa=None, enforce_applicability=True, catalogue, ports, profile=None)[source]

Resume or create the active work unit for one visible filing target.

The visible target is resolved first. If one active unit exists, it is reused after profile-readiness validation and optional rename. If none exists, the law-determined registry revision is selected and a work unit is created.

Return type:

ModeloWorkEnsureResult

Returns:

A ModeloWorkEnsureResult marking whether the unit was reused or newly created.

Parameters:
resolve_modelo_work_address(address, *, catalogue, bucket_id)[source]

Resolve an operator-facing modelo work address to a required ModeloWorkResolution.

Return type:

ModeloWorkResolution

Parameters:
resolve_optional_modelo_work_address(address, *, catalogue, bucket_id)[source]

Resolve an operator-facing modelo work address to a ModeloWorkResolution.

Return type:

ModeloWorkResolution

Parameters:
resolve_modelo_work_address_unit(address, *, catalogue, bucket_id)[source]

Resolve an operator-facing modelo work address to one WorkUnit.

Return type:

WorkUnit

Parameters:
resolve_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, default_for=None, catalogue, resolved_bucket_id, ports)[source]

Resolve a CalculationRevision by exact id or under a modelo work address.

default_for applies the command-specific selector default after the work unit is resolved. A bare exact calculation-revision id bypasses work-address resolution and loads the revision directly. For verify and file only, a positional exact token that names a persisted work unit is reconciled through that unit’s current-revision pointer. This is not an alternate CLI grammar: it closes the application-owned recovery edge where the exact persisted identity initially has no calculation revision, calculation creates the current revision, and the unchanged original invocation must then address it.

Return type:

CalculationRevision

Parameters:
resolve_modelo_revision_pick(*, target, pick=None, catalogue, resolved_bucket_id, calculation_repository, operation)[source]

Resolve and project a revision selection as ModeloResolvedRevisionProjection.

Return type:

ModeloResolvedRevisionProjection

Parameters:
resolve_verifiable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, catalogue, resolved_bucket_id, ports)[source]

Resolve the CalculationRevision that work verify addresses.

Returns the resolved revision in ANY lifecycle state; no draft gate is applied here. Verification-state policy is owned by verify_modelo_revision() under aeat-cli-contract: a revision already out of BORRADOR that carries a granting VerificationReport collapses to that existing report as an idempotent no-op, and the hard refusal is reserved for the inconsistent non-draft/no-granting-report state. Gating BORRADOR here would refuse the idempotent retry before the collapse could fire.

Return type:

CalculationRevision

Parameters:
resolve_fileable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, catalogue, resolved_bucket_id, ports)[source]

Resolve the verified-complete CalculationRevision that work file may consume.

Return type:

CalculationRevision

Parameters:
resolve_exportable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, catalogue, resolved_bucket_id, ports)[source]

Resolve the filed or verified-complete CalculationRevision that modelo export may consume.

Return type:

CalculationRevision

Parameters: