aeat.application.modelo._calculation_helpers module

Shared calculation helpers for modelo application actions.

The helpers load mutable WorkUnit records, resolve their law-determined RegistrySnapshot, and project engine, imported, or amended values into CasillaObservation provenance rows. Amendment helpers reuse the baseline CalculationRevision where a corrected casilla was not overridden, and rebuild overridden rows from the selected snapshot so legal/source grounding is never silently erased.

See also

aeat.application.modelo._calculation_actions:

Uses these helpers before registry-engine execution and persistence.

aeat.application.modelo._amendment_actions:

Reuses amendment observation projection for corrected filing records.

aeat.application.modelo._registry_resources:

Supplies the packaged registry authority used for snapshot resolution.

RegistryCalculationResult:

Registry-engine result whose values and formula entries are projected into typed observations.

load_work_unit_for_calculation(work_units, *, work_unit_id)[source]

Load a mutable aeat.domain.modelos.WorkUnit for calculation.

Missing ids raise WorkUnitNotFoundError. Work units already marked DESCARTADO raise WorkUnitMutationRefusedError, because the calculate path must not create a new revision for a discarded lifecycle record.

Return type:

WorkUnit

Parameters:
resolve_registry_snapshot_for_work_unit(work_unit)[source]

Resolve and return the RegistrySnapshot.

After resolution the snapshot’s revision id is asserted equal to the work unit’s pinned revision_id (D1 calc-time assertion, per the period-revision-resolution ADR ruling 2). Divergence — possible only when the registry’s law-mapping was corrected after the work unit was created, or for units persisted before the strengthened creation gate — raises WorkUnitRevisionDivergenceError directing the operator to re-create the work unit.

The aeat.domain.modelos.WorkUnit revision_id is never passed into the snapshot resolution call; it is only compared against the law-determined resolver answer.

See also

aeat.application.modelo._work_addressing.resolve_registry_revision_for_work_target():

Performs the create-time counterpart of this revision identity assertion.

aeat.application.modelo._action_errors.WorkUnitRevisionDivergenceError:

Refusal raised when the pinned revision no longer matches the law-determined snapshot.

Return type:

RegistrySnapshot

Parameters:

work_unit (WorkUnit)

build_typed_observations(*, engine_result, snapshot)[source]

Build CasillaObservation rows.

Formula targets carry their RegistryCalculationEntry provenance. Non-formula values get legal/source references from the RegistrySnapshot casilla definitions. Any value without a formula entry or registry casilla definition raises aeat.application.modelo.CasillaProvenanceMissingError through aeat.application.modelo._calculation_helpers.casilla_observation_for() rather than emitting an ungrounded row.

Return type:

tuple[CasillaObservation, ...]

Parameters:
external_filing_observations(*, casilla_values, snapshot)[source]

Build CasillaObservation rows for imports.

The RegistrySnapshot supplies the provenance for imported values that have no RegistryCalculationEntry in the current process. This keeps imported AEAT baselines on the same typed-observation contract as locally calculated revisions.

See also

aeat.application.modelo.import_external_filing_evidence():

Persists the external-evidence baseline that consumes these rows.

Return type:

tuple[CasillaObservation, ...]

Parameters:
casilla_observation_for(*, casilla_id, value, entry, registry_casilla)[source]

Project one casilla into a typed observation with full provenance.

Formula entries contribute formula id, operand lineage, and legal/source refs. Non-formula casillas use the CasillaDefinition selected by the RegistrySnapshot. A missing definition is a hard provenance error because emitting a CasillaObservation without legal_refs and source_refs would erase legal grounding.

Return type:

CasillaObservation

Parameters:
amendment_observations(*, corrected_values, overrides, baseline_revision, snapshot)[source]

Build amendment CasillaObservation rows.

The baseline CalculationRevision contributes unchanged observations for casillas the amendment did not override. Newly overridden casillas are rebuilt from the RegistrySnapshot so the persisted amendment revision carries legal/source provenance even when the imported baseline had sparse observation rows. A corrected casilla absent from the snapshot raises aeat.application.modelo.CasillaProvenanceMissingError.

See also

aeat.application.modelo.amend_modelo_revision():

Uses these rows for the corrected amendment revision.

Return type:

tuple[CasillaObservation, ...]

Parameters: