aeat.domain.calculations.registry._record_design_coverage module

Off-load-path record-design coverage and calculation-closure derivations.

calculation_closure_casilla_ids() and calculation_closure_legal_refs() derive bounded closure projections from a ModeloRevision; DisenoCoverageReport remains the advisory full-Diseño inventory.

class DerivedDisenoCasilla(segmento, number, casilla_id=None)

Bases: object

One casilla derived from a registry closure or AEAT Diseño workbook.

segmento carries the AEAT record-segment code (the workbook sheet name) for multi-segment modelos and is None for single-segment modelos. number is the registry/display metadata under review. casilla_id is present only when the row came from a registry calculation closure; full-Diseño coverage rows may have no registry casilla yet and therefore leave it unset.

Parameters:

• segmento (str | None)

• number (str)

• casilla_id (CasillaId | None)

segmento: str | None

number: str

casilla_id: TypeAliasType | None

calculation_closure_casilla_ids(revision, modelo_id)

Return canonical casilla ids in a revision’s calculation closure.

The calculation closure is the set of casillas the cross-connecting calculation engine traverses within this modelo revision:

• every formula.target_casilla_id casilla;

• every casilla referenced inside any formula.expression, walked transitively via the runtime-graph expression_casilla_refs walker;

• every casilla that declares a formula (a computed endpoint) or a binding (a bound endpoint) — the engine-visible casillas;

• every verification-expectation operand casilla (computed_casilla_ids and the reconciliation_total_casilla_ids targets);

• every within-modelo binding source_casilla_ids / source_casilla_id selector casilla, and every within-modelo RelationDefinition.source_casilla_id.

A binding source_casilla_ids / source_casilla_id selector — and a RelationDefinition.source_casilla_id — is excluded from this closure only when it is genuinely cross-modelo: when the selector explicitly names a source_modelo that differs from modelo_id. A cross-modelo selector’s source_casilla_ids / source_casilla_id name casillas on that foreign modelo, not on the modelo whose closure is being derived; the cross-modelo edge enters the current modelo through the bound casilla — the current-modelo casilla that declares the binding (or, for a relation, relation.target_binding) — which is already counted above as a binding endpoint. Folding a foreign-modelo casilla id into this closure would make the completeness gate demand it from the wrong modelo’s registry.

A selector that omits source_modelo or sets it equal to modelo_id is a within-modelo selector: a previous_filing self-binding or a previous_period self-relation names a casilla on the modelo being derived, so that casilla is a genuine closure member and is kept.

References are not normalised through record-design metadata. A formula, binding, relation, or verification token must already be the canonical casilla.id for this revision. A reference token that matches no declared casilla id is kept verbatim so the manifest derivation and registry validation fail loudly on the unresolved canonical reference.

Parameters:

• revision (ModeloRevision) – The ModeloRevision whose formula and binding graph is walked to derive the closure.

• modelo_id (str) – The AEAT modelo identifier used to exclude cross-modelo selector casillas from the closure.

Return type:

frozenset[TypeAliasType]

calculation_closure_record_design_metadata(revision, modelo_id)

Return the (segmento, number) metadata in a revision’s calculation closure.

Metadata projection of calculation_closure_casilla_ids(). The canonical closure never resolves through casilla.number; this function resolves each canonical id token to the declared casilla it names and keeps that casilla’s (segmento, number) record-design metadata.

Parameters:

• revision (ModeloRevision) – The ModeloRevision whose calculation closure to derive.

• modelo_id (str) – Modelo identifier used to scope cross-modelo selectors; selectors whose source_modelo differs from modelo_id are excluded from the closure.

Return type:

frozenset[tuple[str | None, str]]

The closure spans the same surface (formula targets, transitive formula-expression refs, formula/binding endpoint casillas, verification-expectation operands, and within-modelo binding / relation source casillas; only genuinely cross-modelo selectors — those whose source_modelo differs from modelo_id — are excluded, see calculation_closure_casilla_ids()). A reference token is resolved against the casilla id index only:

• a token that matches a casilla id resolves to that exact casilla’s metadata — this is how a multi-segment modelo’s formulas, which reference casillas by the segment-carrying composite id (e.g. DP200014:00562), pin the closure to the correct record segment;

• a token that resolves to no declared casilla is kept as a bare (None, token) metadata placeholder so a calculation that names a casilla the registry never declared still surfaces in the closure.

The calculation-completeness manifest is keyed on canonical casilla.id and carries this metadata only for review and Diseño drift checks.

calculation_closure_legal_refs(revision, modelo_id)

Return legal references carried by a revision’s calculation closure.

Legal-ref projection of calculation_closure_casilla_ids(). The completeness manifest is the reviewed ledger for the calculation closure, so its own legal_refs must equal the refs carried by the closure casillas plus their endpoint formula/binding definitions and verification expectations.

Unresolved closure tokens are skipped here because derive_calculation_completeness_casillas() and the manifest drift gate already surface missing required casillas explicitly.

Parameters:

• revision (ModeloRevision) – The ModeloRevision whose calculation closure legal references are projected.

• modelo_id (str) – Modelo identifier used to scope cross-modelo selectors.

Return type:

frozenset[TypeAliasType]

derive_calculation_completeness_casillas(revision, modelo_id, *, multi_segment, diseno_path=None)

Return the calculation-completeness manifest casilla set for a revision.

Derives the modelo’s calculation closure (calculation_closure_casilla_ids()) and carries each closure casilla’s own registry (segmento, number) metadata. The closure bounds the manifest to exactly the casillas the cross-connecting calculation engine traverses; the registry’s canonical casilla.id — not a five-digit AEAT Diseño tag — names each manifest entry.

This derivation is vocabulary-agnostic. Only Modelo 200’s registry casilla number\ s are genuine five-digit AEAT Diseño tags; the other calculation-bearing modelos identify casillas by semantic slug (iva.cuota-devengada-total) or short ordinal (01-19). The manifest is therefore derived from the modelo’s calculation surface keyed on canonical casilla.id and carrying the registry metadata each closure casilla declares, so it can be authored for any calculation-bearing modelo regardless of its casilla vocabulary.

For a multi_segment modelo the result is segment-aware. A multi-segment modelo reuses the same casilla number across distinct record segments and its formulas reference casillas by the segment-carrying composite id, so the metadata-preserving closure (calculation_closure_record_design_metadata()) already pins each closure casilla to the exact record segment the calculation surface uses. When diseno_path is supplied each segment-scoped metadata pair is additionally verified against the AEAT Diseño de Registros: the Diseño remains authoritative on which record segment carries a number, and a pinned (segmento, number) absent from the Diseño is a derivation error.

For a single-segment modelo segmento is left unset and the closure casilla’s registry number alone carries the reviewed metadata; no Diseño is required because a single-segment modelo’s metadata is unambiguous without one.

A closure reference that resolves to no declared casilla is omitted from the derived set — the calculation-completeness gate then fires on the missing required casilla when it compares the manifest to the declared casillas, which is the gate fulfilling its mission. The drift / coverage tests surface such gaps explicitly.

This is an off-load-path tool. When diseno_path is supplied it parses the multi-megabyte Diseño corpus and must never run on the snapshot-build path.

Parameters:

• revision (ModeloRevision) – The ModeloRevision whose calculation closure to derive into a manifest.

• modelo_id (str) – Modelo identifier; cross-modelo selectors whose source_modelo differs from modelo_id are excluded from the closure.

• multi_segment (bool) – When True, the manifest is segment-aware and a casilla number repeated across distinct segments produces distinct manifest rows; when False, segment metadata is dropped from the manifest key.

• diseno_path (Path | None) – Optional path to an AEAT Diseño workbook used to cross-check that every derived manifest casilla also appears on the published record design.

Return type:

tuple[DerivedDisenoCasilla, ...]

Returns:

Tuple of DerivedDisenoCasilla representing the calculation-completeness manifest.

derive_diseno_coverage_casillas(path, *, multi_segment)

Return DerivedDisenoCasilla items for the full casilla set declared by a Diseño.

Runs read-only record-design extraction against the official AEAT Diseño de Registros source at path and collects every five-digit casilla tag embedded in the field descriptions, including the accounting-statement data-entry fields that feed no calculation.

This is the input to the off-load-path advisory coverage report that inventories form-level data coverage. It is intentionally NOT a load-blocking gate: a modelo whose registry is not yet exhaustively backfilled against the full Diseño is reported as having a coverage gap, not failed at load. The load-blocking gate is keyed on the bounded calculation closure (derive_calculation_completeness_casillas()) instead.

For a multi_segment modelo (e.g. Modelo 200, which reuses the same casilla number across distinct record segments) every casilla carries the workbook sheet name as its segmento, so the same number under two segments yields two distinct metadata pairs. For a single-segment modelo segmento is left unset and the bare number alone identifies the casilla; a number that recurs across sheets of a single-segment Diseño collapses to one metadata pair, matching the bare-number registry behaviour.

This is an off-load-path tool: it parses the multi-megabyte Diseño corpus and must never run on the snapshot-build path.

Return type:

tuple[DerivedDisenoCasilla, ...]

Parameters:

• path (Path)

• multi_segment (bool)

class DisenoCoverageReport(modelo_id, revision_id, diseno_casillas, covered_casillas, coverage_gap_casillas)

Bases: object

An off-load-path advisory inventory of one revision’s Diseño coverage.

Compares a modelo revision’s declared casillas against the full AEAT Diseño de Registros casilla set — every five-digit casilla tag AEAT embeds in the form’s field descriptions, accounting-statement data-entry fields included.

This report is advisory: it is produced off the snapshot-build load path and never reds a load. A modelo whose registry is not yet exhaustively backfilled against the full Diseño is reported here as having a coverage gap, surfaced as information for follow-up authoring. The load-blocking gate is the bounded calculation-completeness gate, not this full-Diseño inventory — that Calculation-completeness is enforced at load; full-Diseño coverage is inventoried off-load-path as an advisory follow-up surface.

Fields:

• modelo_id / revision_id identify the revision inventoried.

• diseno_casillas is the full (segmento, number) set the Diseño declares.

• covered_casillas is the subset the registry also declares — the Diseño casillas the registry has backfilled.

• coverage_gap_casillas is the subset the Diseño declares that the registry does not — the advisory follow-up inventory.

Parameters:

• modelo_id (str)

• revision_id (str)

• diseno_casillas (tuple[DerivedDisenoCasilla, ...])

• covered_casillas (tuple[DerivedDisenoCasilla, ...])

• coverage_gap_casillas (tuple[DerivedDisenoCasilla, ...])

modelo_id: str

revision_id: str

diseno_casillas: tuple[DerivedDisenoCasilla, ...]

covered_casillas: tuple[DerivedDisenoCasilla, ...]

coverage_gap_casillas: tuple[DerivedDisenoCasilla, ...]

property diseno_casilla_count: int

Total (segmento, number) casillas the Diseño declares.

property covered_count: int

Diseño casillas the registry also declares.

property coverage_gap_count: int

Diseño casillas the registry does not yet declare.

build_diseno_coverage_report(path, modelo_id, revision, *, multi_segment)

Return the off-load-path full-Diseño coverage advisory report for a revision.

Extracts the full AEAT Diseño de Registros casilla set (derive_diseno_coverage_casillas()) and compares it against the revision’s declared casillas, keyed on the (segmento, number) metadata. The result is a DisenoCoverageReport that inventories how much of the form’s data surface the registry covers and which Diseño casillas remain to be authored.

This is an advisory inventory, never a load gate. It is produced off the snapshot-build path — it parses the multi-megabyte Diseño corpus — and must never run on the load path. A coverage gap reported here does not fail any modelo: the load-blocking enforcement is the bounded calculation-completeness gate; calculation-completeness is enforced at load while full-Diseño coverage is inventoried off-load-path.

For a multi_segment modelo the comparison is segment-aware: a Diseño casilla under segment S is “covered” only when the registry declares a casilla with the same (S, number) metadata. For a single-segment modelo segmento is unset on both sides and the bare number alone identifies the casilla.

Parameters:

• path (Path) – Path to the official AEAT Diseño de Registros source file.

• modelo_id (str) – The AEAT modelo identifier for the coverage report.

• revision (ModeloRevision) – The ModeloRevision whose declared casillas are compared against the extracted Diseño casilla set.

• multi_segment (bool) – Whether the modelo uses segment-qualified casilla ids.

Return type:

DisenoCoverageReport