cadrumo.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

cadrumo.application.modelo.calculation_actions:

Uses these helpers before registry-engine execution and persistence.

cadrumo.application.modelo.amendment_actions:

Reuses amendment observation projection for corrected filing records.

cadrumo.domain.calculations.registry.authority.bundled_indexed_authority():

Leases the packaged indexed registry generation 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, repository_bucket_id=None)[source]

Delegate calculation target state/addressability to the canonical lifecycle guard.

Return type:

WorkUnit

Parameters:
assert_snapshot_matches_work_unit_revision(work_unit, snapshot, *, period=None)[source]

Raise when the RegistrySnapshot revision diverges from the pinned one.

snapshot’s revision must equal the revision work_unit was pinned to.

This is the single home for the D1 calc-time assertion’s message and exception type: the law-determined revision must equal the revision the work unit was created against, or WorkUnitRevisionDivergenceError directs the operator to re-create the work unit. Divergence is 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.

period names the AEAT natural-key coordinates the message reports; most callers resolve snapshot from work_unit.period and can omit it. A caller that resolves snapshot from a different, caller-supplied period (see cadrumo.application.modelo.result_disposition_resolution._result_disposition_values_for_revision(), which threads the export path’s period through for the Modelo 303 refund-election decision) passes that period so the message names the coordinates the snapshot was actually resolved against.

See also

cadrumo.application.modelo.work_addressing.law_selected_revision_for_work_target():

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

cadrumo.application.modelo.action_errors.WorkUnitRevisionDivergenceError:

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

Return type:

None

Parameters:
resolve_registry_snapshot_for_work_unit(work_unit, *, grade=RegistryAuthorityGrade.FILING, operation=None)[source]

Resolve and return the RegistrySnapshot.

After resolution the snapshot’s revision id is asserted equal to the work unit’s pinned revision_id via assert_snapshot_matches_work_unit_revision() (a calc-time assertion).

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

See also

cadrumo.application.modelo.work_addressing.law_selected_revision_for_work_target():

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

cadrumo.application.modelo.action_errors.WorkUnitRevisionDivergenceError:

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

Return type:

RegistrySnapshot

Parameters:
build_typed_observations(*, engine_result, snapshot)[source]

Build CasillaObservation rows.

The engine result is already the canonical grounded envelope, including text-family casillas that do not appear in its Decimal-only values projection. This boundary verifies every observation still belongs to the selected registry revision, then preserves the envelope unchanged. Any observation without a registry casilla definition raises cadrumo.application.modelo.action_errors.CasillaProvenanceMissingError through cadrumo.application.modelo._calculation_helpers.casilla_observation_for() rather than emitting an ungrounded row.

Core types: RegistrySnapshot.

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

cadrumo.application.modelo.external_import_actions.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 cadrumo.application.modelo.action_errors.CasillaProvenanceMissingError.

See also

cadrumo.application.modelo.amendment_actions.amend_modelo_revision():

Uses these rows for the corrected amendment revision.

Return type:

tuple[CasillaObservation, ...]

Parameters: