cadrumo.application.modelo.calculation_resolution module

Calculation input-channel resolution helpers.

The helpers merge caller, backend, profile, and borrador channels for a RegistrySnapshot, then build the canonical input map consumed by the selected ModeloRevision.

This module is the calculation-service assembly layer between source resolution and engine execution. It delegates source-specific work to the binding resolution helpers, then returns typed channel bundles that application.modelo.calculation_actions.calculate_modelo_revision() can pass to domain.calculations.registry.formula_runtime.calculate_registry_snapshot() and the CalculationRevision persistence boundary.

See also

application.modelo.binding_resolution.resolve_borrador_source_tier()

Resolves the optional borrador tier before the final precedence merge.

application.modelo.binding_resolution.resolve_profile_source_tier()

Resolves profile-sourced bindings as the lowest-precedence tier.

application.aggregation.source_resolution_operations.merge_source_resolutions_by_precedence()

Applies the ordered overlay contract used by this module.

class ResolvedCalculationChannels(bindings, enum_bindings, date_bindings, boolean_bindings, borrador_snapshot_id, bindings_sourced_from_borrador)[source]

Bases: object

Merged engine binding channels for one calculation.

bindings feeds the Decimal channel, enum_bindings feeds string dispatch keys, date_bindings feeds date-valued profile bindings, and boolean_bindings feeds the truth values of bindings whose registry value contract declares the boolean channel. The borrador fields carry the typed snapshot trace from CalculationSourceResolution through to the persisted CalculationRevision.

Parameters:

  • bindings (dict[BindingId, Decimal])

  • enum_bindings (dict[BindingId, str])

  • date_bindings (dict[BindingId, date])

  • boolean_bindings (dict[BindingId, bool])

  • borrador_snapshot_id (str | None)

  • bindings_sourced_from_borrador (tuple[BindingId, ...])

bindings: dict[TypeAliasType, Decimal]
enum_bindings: dict[TypeAliasType, str]
date_bindings: dict[TypeAliasType, date]
boolean_bindings: dict[TypeAliasType, bool]
borrador_snapshot_id: str | None
bindings_sourced_from_borrador: tuple[TypeAliasType, ...]
class ResolvedCalculationInputs(casilla_inputs, text_casilla_inputs)[source]

Bases: object

Canonical per-channel casilla inputs for one engine run.

casilla_inputs feeds calculate_registry_snapshot(inputs=...) and text_casilla_inputs feeds its text_inputs=... channel. Callers receive both together so a string-family casilla cannot be silently dropped on the way to the engine.

Parameters:
casilla_inputs: dict[TypeAliasType, Decimal]
text_casilla_inputs: dict[TypeAliasType, str]
class CalculationReplayPayloads(input_values_by_casilla_id, binding_overrides, row_binding_values, relation_overrides)[source]

Bases: object

Canonical string payloads stored for calculation replay.

The persistence layer stores user-visible inputs as strings, not live Decimal instances. These maps are derived after all source overlays have settled so replay and revision identity use the same canonical values the engine consumed. They are the persisted replay side of the CalculationRevision hash domain, not an independent calculation path.

Parameters:
input_values_by_casilla_id: dict[TypeAliasType, str]
binding_overrides: dict[TypeAliasType, str]
row_binding_values: dict[TypeAliasType, dict[str, str]]
relation_overrides: dict[TypeAliasType, str]
resolve_calculation_binding_channels(*, work_unit, snapshot, casilla_inputs, caller_binding_values, caller_enum_binding_values, backend_binding_values, borrador_snapshot_id, borrador_snapshot_repository, operation, profile)[source]

Resolve all binding channels for work_unit and snapshot.

The work_unit is the WorkUnit whose bucket, filing year, and period select the source-resolution axis. The snapshot is the RegistrySnapshot supplying the revision whose binding channels are being resolved.

The source-precedence ladder is profile, backend, borrador, then caller. The returned ResolvedCalculationChannels contains the merged Decimal, enum, date, and boolean channels, plus any Borrador100SnapshotRepository provenance, after application.modelo.binding_resolution.reject_binding_channel_mismatch() verifies the registry-declared channel shape and application.modelo.binding_resolution.lift_previous_filing_casilla_overrides_to_bindings() mirrors eligible previous-filing casilla overrides onto their binding ids.

Return type:

ResolvedCalculationChannels

Parameters:
resolve_calculation_inputs(*, revision, filing_year, period, backend_casilla_inputs, resolved_bindings, casilla_inputs, text_casilla_inputs=None)[source]

Build the canonical casilla input maps for engine execution.

The revision is the ModeloRevision whose declaration-period and bound casilla inputs are being projected. The Period supplies the filing-period casilla values that the registry declares as inputs.

Declaration-period bindings are projected first, followed by backend casilla inputs, bound casillas resolved from merged binding values, and finally the caller’s explicit casilla overrides. Both returned maps are sorted for stable replay payloads and revision identity.

The two channels are returned together, and never merged, because the registry assigns each casilla to exactly one of them by declared data_type family: the filing_period role is period_code (a string family whose period_code validator accepts 1T, EXT-1T, and every other declared token), while filing_year is year and stays on the Decimal channel.

Return type:

ResolvedCalculationInputs

Parameters:
build_calculation_replay_payloads(*, resolved_inputs, resolved_bindings, resolved_enum_bindings, resolved_date_bindings, resolved_relations, resolved_row_bindings=None, resolved_boolean_bindings=None)[source]

Convert resolved engine inputs into persisted CalculationReplayPayloads.

Casilla and relation Decimals are canonicalized with the domain decimal formatter. Decimal, enum, date, and boolean binding channels share the single binding_overrides replay map (a truth value as true/false) because that is the persisted scalar CalculationRevision contract. Row-indexed bindings are carried in row_binding_values so the row coordinate remains structured for draft and export replay instead of being encoded into a synthetic binding id. The replay payload is built after source precedence and bound-casilla projection so its values match the engine inputs exactly.

A carried relation value is keyed by the binding it folds into, so the relation prefill resolves it on both channels. Replay reads both channels into one namespace, so a relation entry that repeats its binding’s value is dropped; a relation entry that disagrees is kept, and the revision’s channel-uniqueness invariant refuses it rather than choosing a winner.

Return type:

CalculationReplayPayloads

Parameters: