aeat.application.modelo._calculation_source_staging module

Staged source-resolution helpers for bucket aggregation calculations.

These helpers let source resolvers that depend on current-year registry values run the registry engine once without persisting a calculation revision. The staged values feed prorrata and bienes-inversion regularizacion resolvers and add diagnostics for source kinds that would otherwise default to a silent zero.

See also

calculate_modelo_revision_from_bucket_aggregation()

Bucket-backed calculate path that composes these staging helpers.

CalculationSourceResolution

Source-mesh envelope merged and diagnosed by this module.

merge_source_resolutions()

Merge primitive used after staged prorrata and bienes-inversion resolutions are produced.

collect_unhandled_source_diagnostics()

Diagnostic sweep used to surface declared-but-unhandled source kinds.

ProrrataRegularizacionSourceResolver

Resolver fed by materialised current-year prorrata registry values.

BienesInversionRegularizacionSourceResolver

Dependent capital-goods resolver composed with the staged prorrata pass.

calculate_registry_snapshot()

Registry engine invoked without persistence to materialise current-year casilla values for staged resolvers.

Governing vault records

2026-05-20-calculation-source-connectivity-adr and 2026-06-10-calculation-engine-foundations-audit define the source-mesh design and no-dormant-source-resolver audit that govern these staging helpers.

class SourceResolutionRegistryValues(values, initial_casilla_ids, unresolved_casilla_ids=(), missing_casilla_ids=())[source]

Bases: object

Registry-engine values materialised for a staged source resolver.

Parameters:

  • values (Mapping[CasillaId, Decimal])

  • initial_casilla_ids (frozenset[CasillaId])

  • unresolved_casilla_ids (tuple[CasillaId, ...])

  • missing_casilla_ids (tuple[CasillaId, ...])

values: Mapping[TypeAliasType, Decimal]
initial_casilla_ids: frozenset[TypeAliasType]
unresolved_casilla_ids: tuple[TypeAliasType, ...]
missing_casilla_ids: tuple[TypeAliasType, ...]
select(casilla_ids)[source]

Return a narrowed view for one source resolver’s declared dependencies.

Return type:

SourceResolutionRegistryValues

Parameters:

casilla_ids (Iterable[CasillaId])

resolve_prorrata_regularizacion_sources(*, registry_snapshot, work_unit, context, source_resolution, casilla_inputs, text_casilla_inputs, binding_values, enum_binding_values, date_binding_values, relation_values, filing_period_date)[source]

Resolve prorrata and dependent capital-goods staged mesh sources.

Parameters:

  • registry_snapshot (RegistrySnapshot) – The target revision’s RegistrySnapshot, consulted to check whether the revision declares a prorrata_regularizacion-sourced binding at all.

  • work_unit (WorkUnit) – The WorkUnit addressing the target filing, threaded to the staged registry engine run.

  • context (CalculationSourceContext) – The CalculationSourceContext the staged prorrata and bienes-inversion resolvers resolve against.

  • source_resolution (CalculationSourceResolution) – The upstream CalculationSourceResolution mesh envelope the staged resolutions are merged into.

  • casilla_inputs (Mapping[TypeAliasType, Decimal] | None) – Operator- and backend-supplied casilla values that seed the staged registry run.

  • text_casilla_inputs (Mapping[TypeAliasType, str] | None) – Text-typed casilla inputs seeding the staged run.

  • binding_values (Mapping[TypeAliasType, Decimal] | None) – Caller-supplied Decimal binding values overlaid on the source resolution’s own binding values.

  • enum_binding_values (Mapping[TypeAliasType, str] | None) – Caller-supplied enum (string) binding values overlaid on the source resolution’s enum binding values.

  • date_binding_values (Mapping[TypeAliasType, date] | None) – Caller-supplied date binding values overlaid on the source resolution’s date binding values.

  • relation_values (Mapping[TypeAliasType, Decimal] | None) – Caller-supplied relation values overlaid on the source resolution’s relation values.

  • filing_period_date (date | None) – The filing period date used for period-sensitive resolution.

Return type:

CalculationSourceResolution

Returns:

The source resolution unchanged when the revision declares no prorrata_regularizacion binding, otherwise the source resolution merged with the staged prorrata and bienes-inversion resolutions.

materialise_prorrata_regularizacion_current_year_values(*, registry_snapshot, work_unit, casilla_inputs, backend_casilla_inputs, binding_values, enum_binding_values=None, date_binding_values=None, text_casilla_inputs=None, relation_values=None, unresolved_relation_ids=(), unresolved_binding_ids=(), filing_period_date=None)[source]

Materialise the current-year values needed by prorrata_regularizacion.

Parameters:

  • registry_snapshot (RegistrySnapshot) – The target revision’s RegistrySnapshot, used to resolve the current-year casilla ids through the registry engine.

  • work_unit (WorkUnit) – The WorkUnit addressing the target filing, threaded to the staged registry engine run.

  • casilla_inputs (Mapping[TypeAliasType, Decimal]) – Operator- and backend-supplied casilla values that seed the staged registry run.

  • backend_casilla_inputs (Mapping[TypeAliasType, Decimal] | None) – Casilla values already bound by the backend source resolution, seeded into the staged run.

  • binding_values (Mapping[TypeAliasType, Decimal]) – Decimal binding values overlaid on the staged run.

  • enum_binding_values (Mapping[TypeAliasType, str] | None) – Enum (string) binding values for the staged run.

  • date_binding_values (Mapping[TypeAliasType, date] | None) – Date binding values for the staged run.

  • text_casilla_inputs (Mapping[TypeAliasType, str] | None) – Text-typed casilla inputs for the staged run.

  • relation_values (Mapping[TypeAliasType, Decimal] | None) – Relation values for the staged run.

  • unresolved_relation_ids (tuple[TypeAliasType, ...]) – Relation ids still unresolved after the backend pass, propagated so the engine does not treat them as zero.

  • unresolved_binding_ids (tuple[TypeAliasType, ...]) – Binding ids still unresolved after the backend pass, propagated so the engine does not treat them as zero.

  • filing_period_date (date | None) – The filing period date used for period-sensitive resolution.

Return type:

SourceResolutionRegistryValues

Returns:

The narrowed SourceResolutionRegistryValues for the four prorrata current-year casillas, or an empty materialisation when the revision does not declare all of them.

materialise_registry_values_for_source_resolution(*, registry_snapshot, work_unit, casilla_inputs, backend_casilla_inputs, binding_values, enum_binding_values=None, date_binding_values=None, text_casilla_inputs=None, relation_values=None, unresolved_relation_ids=(), unresolved_binding_ids=(), staging_binding_defaults=None, filing_period_date=None)[source]

Run the registry engine without persistence so staged resolvers can read current values.

registry_snapshot is the compiled RegistrySnapshot the engine evaluates the staged current-year values against.

Return type:

SourceResolutionRegistryValues

Parameters:
add_unhandled_source_diagnostics(revision, source_resolution)[source]

Add advisories for declared binding sources not handled by the mesh.

revision is the compiled ModeloRevision whose declared binding sources are checked against the mesh’s owned-source set.

Return type:

CalculationSourceResolution

Parameters:
add_expected_missing_binding_diagnostics(revision, source_resolution)[source]

Mark present-source, no-value binding gaps unresolved instead of silent.

revision is the compiled ModeloRevision whose bound casillas are checked for present-source, no-value binding gaps.

Return type:

CalculationSourceResolution

Parameters:
expected_but_missing_binding_ids(revision, *, owned_sources, resolved_binding_values)[source]

Return direct bound bindings whose present source resolved no value.

revision is the compiled ModeloRevision whose bindings and casillas are scanned for present-source, no-value gaps.

Return type:

tuple[tuple[TypeAliasType, TypeAliasType, BindingSourceKind], ...]

Parameters: