aeat.domain.calculations.registry._bindings module

Data binding helpers for registry-backed factual inputs.

This module owns the CasillaObservation envelope emitted by the formula runtime and the DataBindingDefinition helper surface that turns factual binding values into bound casilla inputs.

See also

domain.calculations.registry._formula_runtime

Runtime that emits typed observations and consumes resolved bound casilla inputs.

domain.calculations.registry._formula_initial_values

Initial-value assembler that calls the bound-casilla helpers here.

domain.calculations.registry._schema

Registry schema definitions for casillas, bindings, and revisions.

class CasillaObservation(**data)[source]

Bases: BaseModel

One typed casilla observation emitted by the formula runtime.

Carries a CasillaId, final decimal.Decimal value, required legal/source provenance, and optional formula lineage. When formula_id is set, the runtime computed this casilla and operand_refs / operand_values trace its inputs while operand_casilla_refs carries the casilla-id-only projection; when formula_id is None the casilla was supplied as input (manual / bound) and the trace fields are empty.

Used as the primary storage for RegistryCalculationResult; derived values and entries views project from it.

Parameters:

  • casilla_id (CasillaId)

  • value (Decimal)

  • formula_id (FormulaId | None)

  • op (str | None)

  • operand_refs (tuple[str, ...])

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

  • operand_values (tuple[Decimal, ...])

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

  • absent_by_design (bool)

casilla_id: CasillaId
value: Decimal
formula_id: FormulaId | None
op: str | None
operand_refs: tuple[str, ...]
operand_casilla_refs: tuple[CasillaId, ...]
operand_values: tuple[Decimal, ...]
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
absent_by_design: bool
class RegistryModeloObservation(**data)[source]

Bases: BaseModel

Observed casilla values from a filed declaration.

Storage is observations: a typed tuple of CasillaObservation carrying full formula provenance. The casilla_values property provides a read-only mapping view for downstream consumers.

Parameters:
modelo: ModeloId
filing_period: Period | None
filing_year: int
period: str
observations: tuple[CasillaObservation, ...]
property casilla_values: Mapping[CasillaId, Decimal]

casilla_id -> Decimal derived from typed observations.

Deliberately a plain @property and NOT a pydantic computed_field: the typed envelope (observations) is canonical storage. Exposing this derived view in JSON would round-trip self-incompatibly under extra='forbid' because the loader would refuse the duplicate field on the way back in.

Type:

Read-only mapping view

class OracleModeloObservation(**data)[source]

Bases: RegistryModeloObservation

Observed casilla values whose source is a live AEAT oracle adapter.

A subtype of RegistryModeloObservation that marks the observation tuple as oracle-originated rather than locally computed. The OracleId field anchors the observation to the LiveCrossReferenceDecision that produced it, so the application layer can route oracle-originated values through the cross-reference policy (synthetic-payload verification, replay quarantine, etc.) without ambiguity about provenance.

Distinct from the parent only by the typed oracle_id field; every other invariant is inherited unchanged.

Parameters:
oracle_id: OracleId
bound_casilla_binding_ids(casilla)[source]

Return primary plus reviewed equivalent bindings for one bound casilla.

The CasillaDefinition must be a bound casilla; the returned BindingId tuple drives bound-value resolution and equivalent-source conflict checks.

Return type:

tuple[TypeAliasType, ...]

Parameters:

casilla (CasillaDefinition)

resolve_bound_casilla_binding_value(casilla, facts)[source]

Resolve equivalent binding facts for one casilla, rejecting disagreements.

A bound CasillaDefinition can declare reviewed alternate bindings when multiple registry source paths represent the same factual amount. Supplying two equivalent source values is legal only if they agree exactly; otherwise accepting either one would silently over- or under-declare the downstream calculation.

Return type:

tuple[Decimal | None, tuple[TypeAliasType, ...]]

Parameters:
resolve_bound_inputs_by_casilla_id(revision, facts)[source]

Resolve factual binding values into input values keyed by canonical casilla.id.

facts is keyed by registry binding id. The binding layer only selects factual values; it does not own legal rates, thresholds, or casilla meaning.

Parameters:
Return type:

dict[TypeAliasType, Decimal]

binding_source_casilla_ids(binding)[source]

Return typed source casilla ids declared by binding families that have them.

Return type:

tuple[TypeAliasType, ...]

Parameters:

binding (DataBindingDefinition)

binding_source_modelo(binding)[source]

Return the typed source modelo declared by binding families that have one.

Return type:

TypeAliasType | None

Parameters:

binding (DataBindingDefinition)

is_layout_binding_selector(selector)[source]

Return True when selector carries the record-field layout shape.

The predicate intentionally mirrors the record-shape keys declared on _ManualInputSelector rather than re-implementing the check via raw key inspection. Validate gate behaviour stays coupled to the typed model: if the manual_input record-shape key set is ever extended or renamed, the layout predicate follows automatically.

Return type:

bool

Parameters:

selector (Mapping[str, object])

selector_model_for_source(source)[source]

Return the strict selector model a binding source validates against.

Read-only accessor over _BINDING_SELECTOR_REGISTRY, the discriminated-union table keyed by BindingSourceKind (the canonical DataBindingDefinition.source axis). Returns the per-family selector model when the source is a registry-declared binding source, or None for mesh-only source kinds that are not legal DataBindingDefinition.source values.

The model-level selector validator on DataBindingDefinition consumes this accessor to promote selector-shape typing to model-construction time without re-deriving the table; the op/fact cross-invariants stay owned by validate_binding_selector_shape() at snapshot build.

Return type:

type[BaseModel] | None

Parameters:

source (object)

validate_binding_selector_shape(binding)[source]

Validate a binding against its source family’s single build-time validator.

Routes the binding through the one per-family validate(binding) -> list[str] validator registered in _BINDING_VALIDATOR_REGISTRY, keyed by BindingSourceKind. Each family validator validates the selector shape (projected through _selector_as_dict() inside selector_against_model(), so the gate sees the SAME normalised mapping the resolve-time helpers see and is never stricter than runtime) and lifts that family’s op/fact cross-invariants to build time. Failures are accumulated as diagnostic strings rather than raised, preserving the underlying pydantic field error, so the snapshot-build gate can collect every failure across a revision in one pass.

For every family — including the five detail-record families (related_party_operation, foreign_asset, atribucion_member, refund_operation, donativo_donor) and previous_filing whose op/fact invariants previously ran only at resolve time — a malformed binding is now rejected at snapshot build rather than only when a taxpayer calculation invokes the resolver.

Sources not in the dispatch table are mesh-only and should not appear on a registry binding; construction rejects them before this build-time validator runs.

Return type:

list[str]

Parameters:

binding (DataBindingDefinition)