cadrumo.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_with_diagnostics()

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.

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[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, operation, source_resolution, casilla_inputs, text_casilla_inputs, binding_values, enum_binding_values, date_binding_values, relation_values, filing_period_date, prorrata_register_repository, bienes_inversion_repository, observation_repository)[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.

  • operation (PinnedAuthorityOperation) – The caller-owned generation-pinned authority operation shared by the staged prorrata and bienes-inversion resolvers.

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

  • prorrata_register_repository (ProrrataRegisterRepositoryProtocol) – Canonical repository for the work unit’s prorrata register.

  • bienes_inversion_repository (BienesInversionIvaRegisterRepositoryProtocol) – Canonical repository for the work unit’s capital-goods IVA register.

  • observation_repository (CalculationObservationRepositoryProtocol) – Canonical repository for the work unit’s persisted calculation observations.

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_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_terminal_origin_diagnostics(revision, source_resolution)[source]

Add advisories where a resolved value’s origin departs from its declaration.

revision is the compiled ModeloRevision whose bindings carry the terminal-origin expectation the mesh’s provenance is audited against.

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.

This is the generic, all-modelos, non-blocking silent-zero advisory. It is deliberately narrower than the M202-only hard-blocking gate in require_modelo_required_bindings_resolved(), which refuses outright on ANY declared non-constant binding with no resolved value at all and carries no exclusion for the three source kinds below. The two gates are not duplicates: this one flags a narrower “present source produced no value” shape without blocking, appropriate for modelos where a missing binding does not by itself invalidate the filing; M202’s stricter gate reflects that a pago fraccionado cannot be computed with any declared input absent (Ley 27/2014 art. 40.2/40.3). Do not widen this advisory to M202-level strictness, and do not narrow M202’s gate to this advisory’s exclusions — the divergence is intentional.

Return type:

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

Parameters: