cadrumo.domain.calculations.registry.snapshot module

Registry snapshot construction and authority-boundary validation.

This module is the canonical home for building a validated snapshot and for the small reference/review projections shared by registry authority consumers. Implementation-only helpers remain private below those public boundaries.

Core types: RegistrySnapshot.

validate_materialized_export_record_families(revision)[source]

Refuse unresolved or mixed field families before a revision enters a snapshot.

Core types: ModeloRevision.

Return type:

None

Parameters:

revision (ModeloRevision)

build_validated_snapshot(modelo, catalogues, *, filing_year, period, on=None, revision_id=None, grade=RegistryAuthorityGrade.FILING, revision_directory=None)[source]

Return a selected snapshot after the caller has validated modelo.

grade names the rung of authority the CALLER needs, and it defaults to the strictest one. That default is the point: it was a bool defaulting to False, so a caller that said nothing silently skipped the revision-review, filing-capability and legal-review checks and received a filing-shaped snapshot it had not earned. Now a caller that says nothing gets the strict path, and a caller needing less must opt DOWN explicitly, in typed and greppable form.

A lower rung is a narrower claim, never a weaker check of the same claim: a caller asking when a modelo is due is not making a filing assertion, and forcing it to would make a scheduling question unanswerable rather than safe.

Core types: ModeloDefinition.

Return type:

RegistrySnapshot

Parameters:
check_snapshot_filing_capability(modelo, revision)[source]

Refuse a filing artifact from a revision that can emit nothing.

A filing-grade snapshot is the entry to producing a draft and an export, so a revision declaring no export layout cannot honour the request no matter what else it carries. Refusing here rather than downstream keeps the absence from reading as an empty-but-valid result: the completeness gate in export_draft checks that every required casilla carries a value, and over an absent layout it has nothing to check and passes.

The check runs after layouts are derived from bindings, so a revision that declares none inline but derives one is capable and is not refused. There is no allowance, allowlist or per-modelo exemption: a modelo the application cannot file is a capability that has not been built yet, never a settled state.

Core types: ModeloDefinition, ModeloRevision.

Return type:

None

Parameters:
check_snapshot_filing_review_tier(modelo, revision, catalogues, legal_ids, *, filing_date)[source]

Validate a filing snapshot’s review boundary and return its weakest tier.

Snapshot construction owns the review boundary. Consumers that need to classify a successful filing snapshot must call this check rather than repeat the revision and legal-reference status predicates.

Core types: ModeloDefinition, ModeloRevision.

Return type:

RevisionReviewStatus

Parameters:
SUBSTANTIVE_LAW_KINDS

Legal-reference kind``s that carry substantive tax law -- rate scales, deduction limits, thresholds -- as opposed to procedural/administrative instruments. Substantive-law kinds are anchored to the tax period's own devengo date (``revision.valid_to), never the presentation-extended window: see legal_window_covers_devengo().

legal_window_covers_devengo(revision, reference)[source]

Return whether reference’s effective window grounds revision.

A revision-scoped legal reference is a filing-specific grounding claim, so the temporal test applied to it depends on WHAT KIND of authority it is – this is the same “form approval is presentation-scoped, substantive law is devengo-scoped” distinction validate_orden_aplicabilidad() already draws for the orden_aplicabilidad field:

  • A substantive-law reference (kind in SUBSTANTIVE_LAW_KINDS – a rate scale, a deduction limit, a threshold) must be in force AT THE REVISION’S OWN DEVENGO DATE (revision.valid_to, the 31 December the tax period closes on – IRPF art. 12). A redaction that only starts partway through the following calendar year, while the return is still being filed, did NOT govern the tax period and must not ground it, even though it overlaps the presentation-extended window below.

  • Every other kind (orden, manual, instruction – procedural or interpretive instruments) keeps the existing presentation-window-tolerant overlap check via RevisionLegalApplicabilityWindow: the orden ministerial approving a modelo form, or a manual’s TFI-documentation annex, is legitimately published AFTER the tax year closes, during the presentation window, and rejecting those on a devengo-only test would reject every correctly-grounded citation in the tree (verified: 13 such pairs, 2026-08-02 severity probe).

Do NOT widen SUBSTANTIVE_LAW_KINDS to admit orden (or narrow it further) without re-running that severity probe – a carve-out here is exactly where this gate can go quietly vacuous.

Core types: ModeloRevision.

Return type:

bool

Parameters:
collect_snapshot_ref_ids(modelo, revision, *, include_deadline_windows=True, include_constructs=True, include_parameters=True)[source]

Return the complete reference closure carried by a registry snapshot.

Core types: ModeloDefinition, ModeloRevision.

Return type:

tuple[set[str], set[str]]

Parameters: