cadrumo.domain.calculations.registry.schema_surfaces module¶

Casilla, relation, export, and record schema models.

class CasillaEvolutionKind(*values)[source]¶

Bases: StrEnum

How a casilla changed between two revisions.

REPURPOSED and RETIRED are not degrees of change: a repurposed casilla still exists and now means something else, a retired one is gone. Reading one as the other would carry a prior year’s value into a box that no longer holds it.

UNCHANGED¶

LABEL_EVOLVED¶

SECTION_EVOLVED¶

REPRESENTATION_EVOLVED¶

LEGAL_REFS_EVOLVED¶

LABEL_AND_LEGAL_REFS_EVOLVED¶

REPURPOSED¶

RETIRED¶

class SemanticRoleCardinality(*values)[source]¶

Bases: StrEnum

Whether a semantic role is shared across casillas or deliberately unique.

SHARED¶

INTENTIONAL_SINGLETON¶

class CasillaContinuidadEvolutionDefinition(**data)[source]¶

Bases: RegistryModel

Declared cross-revision evolution for one casilla continuity chain.

id: RecordId¶

continuidad_id: ContinuidadId¶

from_revision: RevisionId¶

to_revision: RevisionId¶

evolution_kind: CasillaEvolutionKindField¶

legal_refs: LegalRefs¶

source_refs: SourceRefs¶

class CasillaAlias(**data)[source]¶

Bases: RegistryModel

A localized label variant for a casilla, carrying its own grounding.

Used by Plan C’s semantic-role validator: two casillas in different modelos can share a semantic_role even though their primary labels differ, provided each declares the divergent phrasing via an aliases entry with a documented BOE or AEAT source. The text is resolved from the shared locale catalogue; the revision loader derives localization_key from the containing casilla and alias occurrence.

localization_key: str¶

legal_refs: LegalRefs¶

source_refs: SourceRefs¶

get_label(locale)[source]¶

Resolve the alias label through the shared catalogue.

Return type:: str
Parameters:: locale (str)

property label: str¶: Return the strict official-Spanish alias label.

class CasillaConstraints(**data)[source]¶

Bases: RegistryModel

Declarative value constraints applied after a casilla is evaluated.

Captures the legal sign / range rules AEAT mandates per LIRPF / LIVA / LIS articles: a withholding casilla cannot carry a negative value, a deductibility cap restricts the maximum, a non-negativity floor on a cuota líquida prevents arithmetic underflow propagating through downstream formulas.

Each constraint declares its own legal grounding so the engine can surface a BOE permalink in the violation envelope when a computed value falls outside the declared bounds. The runtime raises a typed CasillaConstraintViolationError; the Sheets apply adapter renders the same record as a setDataValidation rule on the corresponding cell so the operator sees the constraint directly in the workbook UI.

sign: CasillaSignConstraintField¶

min_value: DecimalValue | None¶

max_value: DecimalValue | None¶

pattern: str | None¶

min_length: int | None¶

max_length: int | None¶

enum: tuple[str, ...] | None¶

legal_refs: LegalRefs¶

source_refs: SourceRefs¶

violates(value)[source]¶

Return a short reason string if a Decimal value violates this constraint, else None.

Numeric-only violation check preserved for downstream consumers of computed casilla values. Text constraints (pattern, min_length, max_length, enum) are surfaced through the sibling violates_text() method.

Return type:: str | None
Parameters:: value (Decimal)

violates_text(value)[source]¶

Return a short reason string if a text value violates the text constraints, else None.

Checks the four text-shape constraints introduced by Plan B: pattern, min_length, max_length, and enum. Used by consumers that resolve a casilla value into a string at evaluation time.

Return type:: str | None
Parameters:: value (str)

class CasillaDefinition(**data)[source]¶

Bases: RegistryModel

A single AEAT casilla within a modelo revision.

id is the canonical reference identity. number and segmento are reviewed AEAT record-design metadata. For single-segment modelos segmento is unset and number alone is unique within the revision. Multi-segment AEAT modelos (e.g. Modelo 200) reuse the same five-digit number across distinct record segments with a different meaning in each; those casillas carry the AEAT record-segment code in segmento to disambiguate metadata.

id: CasillaId¶

number: str¶

segmento: str | None¶

localization_keys: tuple[str, ...]¶

section: tuple[str, ...]¶

data_type: CasillaDataTypeField¶

required: bool¶

input_kind: InputKindValue¶

formula: FormulaId | None¶

binding: BindingId | None¶

alternate_bindings: tuple[BindingId, ...]¶

export_refs: tuple[ExportFieldId, ...]¶

export_exemption_reason: ExportExemptionReasonValue | None¶

constraints: CasillaConstraints | None¶

form_number: AeatBoxNumber | None¶

continuidad_id: ContinuidadId | None¶

continuidad_origin: CasillaLineageOriginField | None¶

continuidad_evidence: str | None¶

inherited_from: RevisionId | None¶

semantic_role: str | None¶

semantic_role_cardinality: SemanticRoleCardinalityField¶

semantic_role_cardinality_reason: str | None¶

aliases: tuple[CasillaAlias, ...]¶

internal_only: bool¶

legal_refs: LegalRefs¶

source_refs: SourceRefs¶

get_label(locale)[source]¶

Resolve one label scalar through the canonical shared catalogues.

Return type:: str
Parameters:: locale (str)

get_help(locale)[source]¶

Resolve optional help through the same identity and fallback chain.

Return type:: str | None
Parameters:: locale (str)

property label: str¶: Return the strict official-Spanish regulatory label.

class CalculationCompletenessCasilla(**data)[source]¶

Bases: RegistryModel

One required canonical casilla.id in a calculation-completeness manifest.

casilla_id is the authoritative reference key consumed by the validator. number and segmento remain official record-design metadata for drift review: the validator cross-checks them against the referenced casilla, but no consumer may resolve the manifest by those metadata fields.

The manifest enumerates only the casillas inside a modelo’s calculation closure — formula targets, the casillas referenced inside any formula expression, formula and binding endpoint casillas, and verification-expectation operands. Pure accounting-statement data-entry fields that feed no calculation are intentionally absent from this required set.

casilla_id: CasillaId¶

number: str¶

segmento: str | None¶

record_design_metadata()[source]¶

Return the reviewed (segmento, number) metadata pair.

Return type:: tuple[str | None, str]

manifest_key()[source]¶

Return the canonical id plus its reviewed record-design metadata.

Return type:: tuple[str, str | None, str]

class CalculationCompletenessManifest(**data)[source]¶

Bases: RegistryModel

The required calculation-closure casilla set for a modelo revision.

Enumerates the canonical casilla.id values in a modelo’s calculation closure — the casillas the cross-connecting calculation engine traverses: every formula target, every casilla referenced inside a formula expression, every binding and relation endpoint casilla, and every verification-expectation operand. It is derived from the official AEAT Diseño de Registros intersected with the modelo’s calculation surface — Diseño-authoritative on each casilla’s segment, number, and label, but the checked-in reference key is the registry’s canonical casilla.id. The segment/number metadata is retained as reviewed evidence and cross-checked against that id.

The registry validator enforces manifest-required ⊆ declared by canonical casilla.id plus a segment/number metadata check and a legal_refs / source_refs grounding check on each required casilla. A casilla the revision declares but the manifest does not list (a pure accounting-statement field) is not a failure.

manual_extraction flags a manifest authored from a manual read of a PDF-only Diseño that resists machine extraction; the off-load-path drift re-verification skips the machine re-derivation for such manifests and records manual_extraction_reason instead of failing silently.

source_ref: SourceRefId¶

casillas: tuple[CalculationCompletenessCasilla, ...]¶

manual_extraction: bool¶

manual_extraction_reason: str | None¶

legal_refs: LegalRefs¶

source_refs: SourceRefs¶

casilla_ids()[source]¶

Return the frozenset of required canonical casilla.id values.

Return type:: frozenset[TypeAliasType]

validate_family_identity_uniqueness(family, identities)[source]¶

Refuse a revision declaring two members of family under one identity.

A family inherits across editions by identity, so a revision holding the same identity twice makes the merge unanswerable: neither member can be said to supersede the predecessor’s, and neither can be retired without also withdrawing the other. The collision is refused rather than resolved by renaming one of them, because a generated suffix would invent a distinction the corpus does not state.

Parameters:

family (str) – The declaration family the identities belong to.
identities (Sequence[str]) – Each member’s identity, in declaration order.

Raises:

RegistryValidationError – Two or more members share an identity.

Return type:

None