cadrumo.domain.calculations.registry.schema_references module¶

Registry reference, source, and temporal coordinate schema models.

class LegalReferenceKind(*values)[source]¶

Bases: StrEnum

The kind of instrument a legal reference cites.

Spanish instrument names are kept as AEAT and the BOE use them; the meanings belong to those sources and are not paraphrased here.

LEY¶

REAL_DECRETO¶

REAL_DECRETO_LEGISLATIVO¶

REAL_DECRETO_LEY¶

ORDEN¶

REGLAMENTO¶

ACUERDO_INTERNACIONAL¶

DIRECTIVA¶

MANUAL¶

INSTRUCTION¶

class DictionaryCasillaIdGrammar(*values)[source]¶

Bases: StrEnum

The casilla-id grammar a dictionary source publishes.

NUMERIC¶

NUMERIC_OR_SINGLE_UPPERCASE_LETTER¶

class RegistrySnapshotRef(**data)[source]¶

Bases: RegistryModel

Typed coordinates that identify a registry snapshot.

modelo: ModeloId¶

revision_id: RevisionId¶

modelo_year: FilingYear¶

period: RegistryPeriodCode¶

class PeriodOverride(**data)[source]¶

Bases: RegistryModel

The period surface one covered filing year serves, in place of the flat tuple.

Authored when a legal boundary falls inside a year rather than between two of them: a design that applies from a monthly period but only from a later quarterly one serves a strict subset of its own periods in the transition year, and a single flat tuple cannot state that.

year: int¶

periods: tuple[RegistrySelectorPeriodCode, ...]¶

class PeriodSelector(**data)[source]¶

Bases: RegistryModel

Select filing years and periods using explicit years or an inclusive range.

periods is the surface every covered year serves. A year named by period_overrides REPLACES that tuple with its own – typically a strict subset, for a mid-year legal boundary – and the override’s periods need not be a subset of periods, because a transition year can also gain a token the steady state does not carry. Every override year must itself be covered by years or the year_from/year_to range, and no year may be overridden twice. Read the surface through periods_for_year() wherever the filing year is known; declared_periods is the union for the year-less token lookups.

years: tuple[int, ...]¶

year_from: int | None¶

year_to: int | None¶

periods: tuple[RegistrySelectorPeriodCode, ...]¶

period_overrides: tuple[PeriodOverride, ...]¶

includes_year(year)[source]¶

Return whether the selector covers a filing year.

Return type:: bool
Parameters:: year (int)

periods_for_year(year)[source]¶

Return the period surface this selector serves in one filing year.

Return type:: tuple[str, ...]
Parameters:: year (int)

property declared_periods: tuple[Annotated[str, BeforeValidator(func=_validate_registry_selector_period, json_schema_input_type=PydanticUndefined)], ...]¶: Every period token this selector declares in any covered year, in declared order.

class RegistryValidityWindow(**data)[source]¶

Bases: RegistryModel

Common inclusive validity window for every revisioned registry declaration.

Parameters:

valid_from (date)
valid_to (date | None)

valid_from: date¶

valid_to: date | None¶

contains_date(coordinate)[source]¶

Return whether coordinate falls inside this inclusive window.

Return type:: bool
Parameters:: coordinate (date)

class RegistryTemporalBounds(**data)[source]¶

Bases: RegistryModel

Optional delta-authored bounds resolved against a containing window.

valid_from: date | None¶

valid_to: date | None¶

class PeriodScopedValidityWindow(**data)[source]¶

Bases: RegistryValidityWindow

A validity window whose filing-year/period coordinate is mandatory.

Parameters:

valid_from (date)
valid_to (date | None)

period_selector: PeriodSelector¶

class TemporalProjectionDirection(*values)[source]¶

Bases: StrEnum

How a resolved coordinate relates to the declaration supplying it.

AUTHORED¶

BACKWARD¶

FORWARD¶

class OrderedSupportEnvelope[source]¶

Bases: Generic

One implementation of hard-gate admission and newest-authority projection.

floor: TypeVar(CoordinateT, int, date)¶

horizon: TypeVar(CoordinateT, int, date)¶

hard_ceiling: Optional[TypeVar(CoordinateT, int, date)]¶

admits_coordinate(coordinate)[source]¶

Return whether a coordinate lies between the hard support gates.

Return type:: bool
Parameters:: coordinate (CoordinateT)

projection_coordinate(coordinate)[source]¶

Map an admitted coordinate to the newest authored coordinate.

Return type:: CoordinateT | None
Parameters:: coordinate (CoordinateT)

clamp_coordinate(coordinate)[source]¶

Return the admitted coordinate nearest coordinate.

A declaration dated outside the gates is read against the vocabulary in force at the nearest supported edge, never at an unsupported date.

Return type:: CoordinateT
Parameters:: coordinate (CoordinateT)

class DateSupportEnvelope(**data)[source]¶

Bases: RegistryModel, OrderedSupportEnvelope[date]

Hard gates and authored horizon on an effective-date axis.

Parameters:

floor (date)
horizon (date)
hard_ceiling (date | None)

floor: date¶

horizon: date¶

hard_ceiling: date | None¶

class TemporalSupportEnvelope(**data)[source]¶

Bases: RegistryModel, OrderedSupportEnvelope[int]

Hard gates and authored horizon shared by forward-projecting registries.

floor and hard_ceiling are refusal boundaries. horizon is the last explicitly authored coordinate, not an implicit ceiling: when no hard ceiling exists, a consumer may carry the declaration at the horizon forward. The actual projection remains a consumer decision and is exposed explicitly by projection_coordinate().

floor: FilingYear¶

horizon: FilingYear¶

hard_ceiling: FilingYear | None¶

property years: tuple[int, ...]¶: Enumerate the explicitly authored span, both bounds inclusive.

admits_coordinate(coordinate)[source]¶

Return whether coordinate is inside the envelope’s hard gates.

Return type:: bool
Parameters:: coordinate (int)

projection_coordinate(coordinate)[source]¶

Map an admitted coordinate to its authored coordinate, carrying the horizon forward.

Return type:: int | None
Parameters:: coordinate (int)

date_envelope()[source]¶

Project the filing-year envelope onto the effective-date axis.

Every date-addressed registry declaration shares this one envelope, so a governed fact never states a floor or ceiling of its own.

Return type:: DateSupportEnvelope

class LegalReference(**data)[source]¶

Bases: RegistryModel

Legal-authority citation row carried by registry definitions.

Parameters:

id (LegalRefId)
evidence_tier (Annotated[Literal[EvidenceTier.LEGAL_AUTHORITY], ~pydantic.functional_validators.BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
authority (Annotated[PublishingAuthority, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
kind (Annotated[LegalReferenceKind, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
corpus_ref (str)
document_id (str)
article (str | None)
section (str | None)
permalink (Annotated[str, AfterValidator(func=~cadrumo.domain.calculations.registry.schema_references._validate_registry_external_link)])
published_at (date | None)
effective_from (date)
effective_to (date | None)
consolidated_as_of (date | None)
review_status (Annotated[RevisionReviewStatus, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base._coerce_revision_review_status, json_schema_input_type=PydanticUndefined)])
reviewed_at (date | None)
reviewed_by (str | None)
notes (str | None)
required_text (tuple[str, ...])
forbidden_text (tuple[str, ...])
corpus_tier (Annotated[CorpusTier, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)] | None)
governs_periods_from (date | None)
governs_periods_to (date | None)

id: LegalRefId¶

evidence_tier: Annotated[Literal[EvidenceTier.LEGAL_AUTHORITY], BeforeValidator(coerce_enum_member(EvidenceTier))]¶

authority: PublishingAuthorityField¶

kind: LegalReferenceKindField¶

corpus_ref: str¶

document_id: str¶

article: str | None¶

section: str | None¶

permalink: RegistryExternalLink¶

published_at: date | None¶

effective_from: date¶

effective_to: date | None¶

consolidated_as_of: date | None¶

review_status: RevisionReviewStatusField¶

reviewed_at: date | None¶

reviewed_by: str | None¶

notes: str | None¶

required_text: tuple[str, ...]¶

forbidden_text: tuple[str, ...]¶

corpus_tier: CorpusTierField | None¶

Which kind of corpus evidence corpus_ref resolves to, when declared.

Deliberately optional and deliberately two-valued. Optional: nothing in the committed catalogue declares it today, so adding the field cannot itself introduce a new refusal – authoring it is opt-in, verified only when present. Two-valued: a paraphrase with no operative text of its own must never become a declarable tier (a stub calling itself an excerpt would pass silently); that shape stays a build-time refusal via the dispositive-content check, never a legal state this field can assert. Verified against the bundled corpus file, not merely typed, by _legal.py’s grounding check – this field states a claim; the verifier is what makes the claim mean something.

governs_periods_from: date | None¶

Earliest devengo this provision governs, when it reaches back before force.

effective_from / effective_to record when a norm entered and left FORCE. A retroactive provision governs tax periods that closed before it existed: RDL 13/2025, in force from 2025-11-27, extends the La Palma deduction “durante los periodos impositivos 2022, 2023, 2024 y 2025” in its own operative text. Checking such a citation against the in-force window rejects a correct grounding, and the cheapest way to silence that refusal is to backdate effective_from – which misstates when the norm came into force and corrupts every other consumer of that field.

So reach is declared here, separately, and only ever by an author who has read the clause that states it. Absent, the governed span IS the in-force span, so adding this field relaxes no existing citation. The declaration is deliberately retroactive-only: it must precede effective_from, because a forward-reaching value would let a stale citation ground a period its norm never governed.

governs_periods_to: date | None¶

Latest devengo this provision governs; None leaves the reach open.

Only meaningful alongside governs_periods_from, which the validator requires.

source_window_applies_across(*, applies_from, applies_to, span_from, span_to)[source]¶

Report whether a source applicability window overlaps one date span.

The ONE definition of the overlap rule, shared by every carrier of an applicability window so that a diagnostic copy of a source cannot answer the question differently from the source itself. An open bound means the window is open in that direction, never that it is unknown; deciding whether an absent bound is admissible belongs to the caller, before it asks.

Return type:

bool

Parameters:

applies_from (date | None)
applies_to (date | None)
span_from (date)
span_to (date | None)

class SourceReference(**data)[source]¶

Bases: RegistryModel

Official-source evidence row with bundled-corpus integrity metadata.

Parameters:

id (SourceRefId)
evidence_tier (Annotated[EvidenceTier, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
authority (Annotated[PublishingAuthority, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
kind (Annotated[RegistrySourceKind, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
corpus_path (str)
sha256 (ContentDigest)
bytes (int)
retrieved_at (date)
published_at (date | None)
applies_from (date | None)
applies_to (date | None)
dictionary_casilla_id_grammar (Annotated[DictionaryCasillaIdGrammar, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
record_design_epoch (str | None)
design_authority (Literal['authoritative', 'provenance_only'])
source_url (Annotated[str, AfterValidator(func=~cadrumo.domain.calculations.registry.schema_references._validate_registry_external_link)])
review_status (Annotated[RevisionReviewStatus, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base._coerce_revision_review_status, json_schema_input_type=PydanticUndefined)])
period_selector (PeriodSelector | None)
corpus_tier (Annotated[CorpusTier, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)] | None)

id: SourceRefId¶

evidence_tier: EvidenceTierField¶

authority: PublishingAuthorityField¶

kind: RegistrySourceKindField¶

corpus_path: str¶

sha256: ContentDigest¶

bytes: int¶

retrieved_at: date¶

published_at: date | None¶

applies_from: date | None¶

applies_to: date | None¶

dictionary_casilla_id_grammar: DictionaryCasillaIdGrammarField¶

Exact casilla-id grammar published by a dictionary source.

The default accepts the numbered ids used by every ordinary AEAT dictionary. The extension is an evidence claim tied to the hash-pinned source row, not a parser-side modelo, source-id, or year exception: when a reviewed dictionary publishes its one-letter annex boxes, that source declares the wider grammar. Its applies_from / applies_to window remains the temporal authority for the source itself.

record_design_epoch: str | None¶

design_authority: DesignAuthority¶

source_url: RegistryExternalLink¶

review_status: RevisionReviewStatusField¶

period_selector: PeriodSelector | None¶

Disambiguates two designs that share one applies_from/applies_to window.

Deliberately optional and deliberately reuses PeriodSelector – the registry’s one period-selector shape, already carrying the AEAT-token vocabulary (RegistrySelectorPeriodCode) – rather than inventing a second grammar. applies_from/applies_to alone cannot express two real AEAT designs published for the SAME year that govern different PERIODS within it: M303 published one whole-year 2018 record design and a second covering every period except the last (quarter 4 / month 12), and a 2021 pair split at period 07 (one design “hasta periodo 06”, the successor “desde periodo 07”). Both members of each pair carry an identical nominal date window, so nothing before this field could tell a record-design resolver’s caller which one to pick for a given filing period. Declare it only for a design whose own filename or published text states the period boundary; leave it undeclared rather than infer one.

corpus_tier: CorpusTierField | None¶

Mirrors LegalReference.corpus_tier in philosophy, recalibrated here.

Same two-valued, verified-not-merely-typed contract: optional so adding the field cannot itself introduce a refusal, and deliberately two-valued so a paraphrase can never become a declarable tier – that shape stays a build-time refusal, never a state this field can assert. The calibration is NOT reused from LegalReference.corpus_tier: this model’s corpus_path is a bare repository-relative path with no #anchor convention (LegalReference.corpus_ref is path#anchor), so a resolved-anchor read does not apply here, and the size floor is calibrated against THIS model’s own observed population, not LegalReference’s. The excerpt/full-text duality only exists for corpus_path entries under corpus/normatives/ – the same BOE/AEAT norm-text tree LegalReference.corpus_ref resolves into, which is why a form_spec source can legitimately point at the exact file a LegalReference entry also cites. A design workbook, manual PDF, XSD or data dictionary under corpus/aeat_official/ has no such duality – verified by _corpus_catalogue.py’s check, which refuses the field outside corpus/normatives/ rather than silently accepting a claim the concept does not apply to.

applies_across(span_from, span_to)[source]¶

Report whether this source’s applicability window overlaps one date span.

Delegates to source_window_applies_across(), which is the one definition of the overlap rule. Callers keep their own policy on whether a missing bound is admissible – a record-design binary must declare applies_from, an evidence-backed source cell must declare both – and apply it before asking this question.

Return type:

bool

Parameters:

span_from (date)
span_to (date | None)

property supports_single_uppercase_letter_casilla_ids: bool¶: Whether this exact reviewed dictionary declares the annex-id grammar.

governed_period_span(reference)[source]¶

Return the devengo span reference governs, which may precede its force.

Defaults to the in-force window, so a reference that declares nothing is tested exactly as before – the retroactive fields cannot relax a citation by existing. A reference that DOES declare reach is tested against the declared span, because that is the axis its citation defends: RDL 13/2025 is in force only from 2025-11-27 yet governs periods 2022 through 2025 by its own operative text, so the 2024 devengo it grounds is inside its reach and outside its force.

The declaration is validated retroactive-only at the model boundary, so this can widen a span backwards but never forwards.

Return type:: tuple[date, date | None]
Parameters:: reference (LegalReference)