cadrumo.domain.calculations.registry.relations module

Cross-filing fold requirements and values for relation-prefill bindings.

A relation_prefill binding declares a fold from another modelo’s filed values – or from an earlier period of this one – into a slot of the target filing. This module turns those declarations into the source requirements that must be satisfied before the target modelo can be calculated, and resolves the folded values once the source observations are available.

The fold used to be declared by a separate relation family keyed by its own identifier. It is now the binding’s own provider, so the binding id is the key everywhere: one declaration, one identity, one inheritance rule.

See also

cadrumo.domain.calculations.registry.bindings_previous_filing

Same requirement record reused by direct previous-filing carries.

cadrumo.domain.calculations.registry.observation_fold

Observation fold helpers used to gather source casilla values.

source_presence_gaps(*, required_source_casilla_ids, source_presence_groups, observed_source_casilla_ids)[source]

Return missing mandatory casillas and unsatisfied any-of groups.

This is the single enforcement primitive for registry-derived previous- filing source presence. Adapters and application gates consume the same result instead of reinterpreting candidate sets independently.

Return type:

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

Parameters:
class RegistryFoldRequirement(**data)[source]

Bases: BaseModel

One source-filing requirement for a cross-filing fold-in.

The single unified requirement record for both fold mechanisms: a cross-modelo relation_prefill fold (target_bindings populated) and a same-modelo direct previous_filing carry (binding_ids populated). Both the source-period and source-casilla axes are PLURAL so the record is a superset of the two shapes: a relation-prefill requirement fans plural periods against a single source_casilla_ids member, while a previous_filing requirement carries a single periods member against plural source_casilla_ids. legal_refs and source_refs retain the originating binding’s grounding for operator diagnostics.

Consumed by relation_source_requirements(), resolve_relation_values_from_observations(), and cadrumo.domain.calculations.registry.bindings_previous_filing.previous_filing_observation_requirements().

Parameters:

data (Any)

source_modelo: ModeloId
filing_year: FilingYear
filing_periods: tuple[Period, ...]
periods: tuple[RegistrySelectorPeriodCode, ...]
source_casilla_ids: tuple[CasillaId, ...]
required_source_casilla_ids: tuple[CasillaId, ...] | None
source_presence_groups: tuple[tuple[CasillaId, ...], ...]
binding_ids: tuple[BindingId, ...]
target_bindings: tuple[BindingId, ...]
dependency_role: RelationDependencyRoleField | None
dependency_treatment: RelationDependencyTreatmentField | None
aggregation_op: RelationAggregationOp | None
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
property enforced_source_casilla_ids: tuple[CasillaId, ...]

Return the registry-declared mandatory subset, defaulting to every candidate.

relation_prefill_bindings_for_period(revision, *, period=None)[source]

Return this revision’s relation-prefill bindings applicable to a period.

The binding’s own applicability is what scopes it now; the relation’s target_periods moved there in the same change that folded the relation into the provider, so period scoping has one home rather than two.

Core types: ModeloRevision.

Return type:

tuple[tuple[BindingDefinition, RelationPrefillProvider], ...]

Parameters:
relation_requirement_index(requirements)[source]

Index canonical fold requirements by every target binding they satisfy.

relation_source_requirements deliberately coalesces source filings that satisfy more than one binding. Consumers nevertheless need a direct binding-id lookup to project the one requirement’s source identity, treatment, and grounding. Keeping that fan-out here means every consumer gets the same requirement object instead of reconstructing partial metadata with a local comprehension.

Return type:

dict[TypeAliasType, RegistryFoldRequirement]

Parameters:

requirements (Iterable[RegistryFoldRequirement])

relation_source_requirements(revision, *, filing_year, period)[source]

Return requirement records needed to resolve relation prefills for a filing.

Parameters:

  • revision (ModeloRevision) – The ModeloRevision whose relation-prefill bindings to inspect.

  • filing_year (int) – Target filing year; combined with each provider’s temporal member to derive the expected source-modelo filing year.

  • period (str) – Target period token; filters bindings by applicability and seeds the source-period derivation.

Return type:

tuple[RegistryFoldRequirement, ...]

Returns:

RegistryFoldRequirement rows keyed by source modelo/year/period and source casilla.

resolve_relation_values(revision, external_outputs, *, period=None)[source]

Resolve relation-prefill values from caller-supplied external outputs.

external_outputs is keyed by target binding id. copy folds one Decimal through unchanged; sum adds the tuple of matched per-period values.

Parameters:

  • revision (ModeloRevision) – The ModeloRevision whose relation-prefill bindings are resolved against the supplied outputs.

  • external_outputs (Mapping[TypeAliasType, Decimal | tuple[Decimal, ...]]) – Caller-supplied per-binding values keyed by BindingId; a decimal.Decimal under copy aggregation or a tuple of Decimals under sum.

  • period (str | None) – Optional period token; restricts active bindings to those whose applicability admits it.

Return type:

dict[TypeAliasType, Decimal]

resolve_relation_values_from_observations(revision, observations, *, filing_year, period)[source]

Resolve relation-prefill values from normalized filed-declaration observations.

Parameters:
Return type:

dict[TypeAliasType, Decimal]

Returns:

Resolved BindingId values suitable for cadrumo.domain.calculations.registry.formula_runtime.calculate_registry_snapshot().

relation_prefill_values_as_binding_values(revision, values, *, period=None)[source]

Project resolved relation-prefill values onto their binding ids.

Relation absorption makes the fold slot and its former target binding one declaration. This small projection remains useful at boundaries that receive a pre-resolved map and need to merge it with ordinary binding inputs; it deliberately accepts only the active provider binding ids and never translates a retired relation id.

Core types: ModeloRevision.

Return type:

dict[TypeAliasType, Decimal]

Parameters: