cadrumo.domain.calculations.registry.formula_runtime_ops module

Formula-runtime operation helpers for registry calculations.

The formula evaluator delegates arithmetic dispatch, dated parameter lookup, rounding, and input validation here while executing ModeloRevision formula graphs. Helpers raise RegistryValidationError so domain.calculations.registry.formula_runtime.calculate_registry_snapshot() reports contract failures through the registry error channel.

See also

domain.calculations.registry.formula_runtime

Snapshot evaluator that calls these helpers while materialising RegistrySnapshot outputs.

domain.calculations.registry.runtime_graph

Formula graph walkers that discover the casilla, binding, relation, and parameter refs consumed before operation dispatch starts.

domain.calculations.registry.authority.ValidatedRegistryAuthority

Registry authority loaded by read_parameter() for ad hoc parameter reads outside snapshot execution.

exception UnresolvedFormulaDependencyError(dependency_ids)[source]

Bases: RegistrySnapshotError

Raised internally when a non-blocking source gap makes a formula unresolved.

Shared between formula_runtime and its per-family op-evaluator siblings (e.g. _formula_runtime_irnr) so a family module can signal a deferred dependency without importing back into the dispatcher module.

Parameters:

dependency_ids (tuple[str, ...])

Return type:

None

code
class RegistryUnresolvedOutcomeReason(*values)[source]

Bases: StrEnum

Closed reason catalogue for typed formula outcomes with no Decimal value.

M210_BASELINE_TIPO_DEFERRED
M210_CONVENIO_RATE_MISSING
exception UnresolvedFormulaOutcomeError(reason, *, context)[source]

Bases: RegistrySnapshotError

Raised internally when a formula emits a typed unresolved outcome.

Parameters:
Return type:

None

code
numeric_casilla_value(casilla_id, ctx)[source]

Read a resolved numeric casilla value from the evaluation context.

Generic accessor shared by the M210/IRNR, M131 módulos, and M303 módulos IVA formula-op families; each raises UnresolvedFormulaDependencyError the same way for a casilla deferred by a non-blocking source gap.

Return type:

Decimal

Parameters:
evaluate_args_op(op, args)[source]

Evaluate a resolved formula operation over decimal operands.

Operation names mirror FormulaExpression op values consumed by domain.calculations.registry.formula_runtime.calculate_registry_snapshot().

Return type:

Decimal

Parameters:
resolve_bracket(parameter, base, date_context)[source]

Resolve a bracket-table ParameterDefinition for a base amount.

The parameter’s bracket date axis must be present in date_context so registry-authored validity windows select exactly one bracket row.

Return type:

Decimal

Parameters:
resolve_dated_value(parameter, date_context)[source]

Resolve the one dated value a ParameterDefinition selects.

Exactly one DatedValue must match the selected date axes for the parameter lookup to be deterministic.

Returns the RECORD rather than its scalar, because a value can carry more than the number: a threshold’s comparison operator moves independently of its amount, so a caller applying a threshold needs the value and the operator that the same redaction fixed. resolve_parameter() delegates here so the selection lives in one place and the two cannot drift.

Return type:

DatedValue

Returns:

The single matching DatedValue.

Raises:

RegistryValidationError – If the parameter declares no values, a required date axis is absent from date_context, or the match is not exactly one.

Parameters:
resolve_parameter(parameter, date_context)[source]

Resolve one dated scalar from a ParameterDefinition.

Return type:

Decimal

Returns:

The selected value’s scalar.

Parameters:
resolve_scalar_parameter(parameter_id, ctx, *, op)[source]

Resolve a scalar parameter and record its runtime provenance.

Formula-operation families share the same scalar type contract and must record the parameter id alongside the resolved Decimal in their common evaluation context. Keeping both actions together prevents a successful lookup from escaping the explainability surface.

Return type:

Decimal

Parameters:

  • parameter_id (str)

  • ctx (_EvalContext)

  • op (str)

resolve_keyed_bracket(parameter, *, key, filing_year)[source]

Resolve one keyed-bracket row for a filing year.

A missing parameter or key is the caller’s explicit “not tabled” signal; overlapping matching windows are a contradictory registry definition and therefore fail closed instead of selecting an arbitrary first row.

Return type:

Decimal | None

Parameters:
apply_rounding(value, rounding)[source]

Apply a registry rounding rule to a decimal formula result.

money-2 uses core.money.rounding.round_to_cents(); integer uses half-up quantization for registry-authored integer targets; integer-ceiling quantizes with decimal.ROUND_CEILING for the targets whose governing provision takes the result to the next unit up rather than to the nearest one (LIVA art. 104.Dos, “se redondeará en la unidad superior”). ROUND_CEILING leaves an already-integral value untouched, so a 50 % ratio stays 50.

ROUND_CEILING moves toward positive infinity, which differs from away-from-zero for a negative operand. Every integer-ceiling target today is a registry-constrained non-negative percentage (sign = "non_negative", min_value = "0"), so the two readings coincide; a future negative-capable target must state which reading its provision means before enrolling here.

Return type:

Decimal

Parameters:
reject_non_decimal(items, label)[source]

Reject non-decimal values before formula runtime consumption.

Return type:

None

Parameters:
validated_decimal_input_casilla_ids(inputs, *, revision)[source]

Canonicalise decimal input keys against a ModeloRevision.

Raw string keys become validated CasillaId values, then domain.calculations.registry.casilla_membership.undeclared_casilla_ids() rejects inputs outside the revision’s declared casilla set.

Return type:

dict[CasillaId, Decimal]

Parameters:
reject_non_string(values, label)[source]

Reject empty or non-string external values before registry validation.

Return type:

None

Parameters:
reject_unknown_external_values(items, known_ids, label)[source]

Reject external ids not declared by the current registry snapshot.

Keyed on ids alone: the gate screens WHICH ids arrived, never what they carry, so every external channel – Decimal, truth value, date or enum – is screened by this one function rather than by a per-channel copy.

Return type:

None

Parameters:
read_parameter(modelo_id, revision_id, parameter_id, *, date_context, operation=None)[source]

Read a registry parameter through ValidatedRegistryAuthority.

The ad hoc public helper loads the same validated registry authority used by snapshot callers, narrows to the selected ModeloRevision, and delegates the dated value lookup to resolve_parameter().

When no operation is supplied, the helper leases one indexed authority generation for the point lookup; it never traverses a whole authority graph.

Return type:

Decimal

Parameters: