cadrumo.domain.calculations.registry.binding_terminal_origin module

The authored expectation of where a binding’s value ultimately comes from.

Runtime provenance already records the terminal nodes a resolver actually reached. What it cannot say on its own is whether those nodes are the ones the declaration intended: a binding that silently resolves from a derived calculation instead of the filed casilla it names is still a complete-looking result. A TerminalOriginExpectation is the compile-time half of that pair – the authored claim that runtime provenance is audited against, which is what makes the claim falsifiable rather than decorative.

The expectation states four things per admitted origin: the class of terminal fact, its role in the provenance graph (reusing the existing CalculationSourceLineageRole), how many such nodes must appear, and whether each must carry an evidence fingerprint. The cardinality axis is what keeps “no rows found” distinguishable from “rows were required and are missing”: zero_or_more is a declaration that emptiness is legitimate, never a default.

TerminalOriginCardinality

How many terminal nodes of one origin class the resolved graph must carry.

alias of Literal[‘exactly_one’, ‘at_least_one’, ‘zero_or_more’]

TerminalOriginFingerprint

Whether each terminal node of this class must carry an evidence fingerprint.

alias of Literal[‘required’, ‘optional’]

class TerminalOriginClass(*values)

Bases: StrEnum

The closed set of terminal fact classes a binding value can rest on.

A terminal origin is where derivation stops: the persisted fact that is not itself computed from another registry source within the same resolution.

OPERATOR_INPUT

A value the operator supplied directly, answerable and attributable.

DESIGN_CONSTANT

A byte run AEAT fixes in the diseño de registro; no operator supplies it.

PROFILE_FIELD

A field of the taxpayer’s censo/profile record.

FILED_MODELO_CASILLA

A casilla value of an immutable, already-filed modelo revision.

LEDGER_AGGREGATE

A fold over classified ledger transactions.

INVOICE_CATALOGUE

A fold over the invoice catalogue, in either or both directions.

PERCEPTOR_OBSERVATION

A per-perceptor retención observation from its dedicated store.

DETAIL_RECORD

A row of an authored or pulled detail-record family.

DERIVED_CALCULATION

A value produced by another calculation rather than a persisted fact.

class TerminalOriginExpectation(**data)

Bases: RegistryModel

One admitted terminal origin and the shape the resolved graph must show.

Parameters:

data (Any)

source_class: Annotated[TerminalOriginClass, BeforeValidator(coerce_enum_member(TerminalOriginClass))]

role: Annotated[CalculationSourceLineageRole, BeforeValidator(coerce_enum_member(CalculationSourceLineageRole))]

cardinality: TerminalOriginCardinality

fingerprint: TerminalOriginFingerprint