cadrumo.domain.calculations.registry.queries module¶

Typed read API for the legacy validated-model introspection surfaces.

RegistryQueryService wraps a ValidatedRegistryAuthority and exposes structured report objects for the CLI list, describe, casillas, formulas, and bindings commands. Queries narrow to a single ModeloDefinition and then to one ModeloRevision selected by filing year, period, and optional revision id.

This service is intentionally not the indexed runtime bridge. Production operations that hold a PinnedAuthorityOperation call its typed modelo_directory/revision_for_context methods directly. The explicit enumeration methods below remain available only for diagnostic surfaces whose contract genuinely requires the complete validated graph.

class ResolvedRegistryQueryContext(**data)[source]¶

Bases: BaseModel

One resolved registry query context, returned by both resolution forms.

RegistryQueryService reaches a modelo revision by two routes: an unscoped lookup that narrows by period token alone, and a scoped lookup that resolves a snapshot for an explicit filing year. Both routes return this context, so every query method and report builder consumes one typed shape instead of two positional tuples whose arity and element meaning differed. The unscoped route leaves filing_year unset, which is why it stays optional here.

This is deliberately narrower than a RegistrySnapshot: a snapshot requires a filing year and carries the whole legal, source, and expectation authority, none of which the unscoped period query has or needs to answer a read-only introspection request.

Parameters:: data (Any)

definition: ModeloDefinition¶

revision: ModeloRevision¶

revision_ids: tuple[str, ...]¶

filing_year: int | None¶

registry_period: RegistrySelectorPeriodCode | None¶

class RegistryQueryService(authority)[source]¶

Bases: object

Legacy introspection facade over the eager validated authority graph.

The constructor deliberately accepts only ValidatedRegistryAuthority. It must not be widened to accept an indexed reader: indexed consumers use the already-pinned operation directly, keeping eager traversal visible and preventing a second selection implementation from drifting from the canonical runtime contract.

Parameters:: authority (ValidatedRegistryAuthority)

modelo_codes()[source]¶

Return deterministic modelo identifiers from the authority index.

This is the explicit bulk-enumeration seam for callers that need a catalogue of model identifiers. It deliberately does not expose the authority’s eager modelos graph; a subsequent operation must ask for the revision it actually needs.

Return type:: tuple[str, ...]

revision_for_scope(modelo, *, filing_year, period, as_of=None, grade=RegistryAuthorityGrade.APPLICABILITY)[source]¶

Return exactly the revision selected for one explicit operation scope.

The report path owns canonical temporal and grade selection; callers that need revision payload fields consume this selected result instead of walking every revision in an authority-wide model graph.

Return type:

ModeloRevision

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)
grade (RegistryAuthorityGrade)

revision_by_id(modelo, revision_id)[source]¶

Return one exact revision component by canonical identity.

Return type:

ModeloRevision

Parameters:

modelo (str)
revision_id (str)

source_exists(source_reference_id)[source]¶

Return whether one source-reference metadata row is enrolled.

Return type:: bool
Parameters:: source_reference_id (str)

iter_modelo_revisions(*, modelo_codes=None)[source]¶

Explicitly enumerate revision components for diagnostics.

Bulk walks are intentionally named and deterministic. They are for source inventories and other diagnostics that genuinely need every revision; ordinary runtime consumers should use revision_for_scope().

Return type:: tuple[tuple[str, ModeloRevision], ...]
Parameters:: modelo_codes (tuple[str, ...] | None)

iter_modelo_definitions()[source]¶

Explicitly enumerate complete model metadata for diagnostics.

This is intentionally separate from point lookup. Support reports and source inventories are declared bulk operations; ordinary calculation consumers must use a selected revision method instead.

Return type:: tuple[ModeloDefinition, ...]

list_modelos(*, year=None, domain=None)[source]¶

Return a catalogue listing of all registered modelos.

Each entry is a lightweight ModeloListRow carrying only summary fields — no revision details are resolved. The rows are sorted ascending by modelo code.

Parameters:

year (int | None) – When supplied, restricts the listing to modelos that have at least one revision whose period_selector covers the given filing year. None returns all registered modelos.
domain (TaxDomain | None) – When supplied, restricts the listing to modelos whose registry TaxDomain equals the requested tax family (e.g. TaxDomain("iva")). None returns every family. The year and domain filters compose: passing both narrows to modelos that satisfy each.

Return type:

ModeloListReport

Returns:

A ModeloListReport containing the matching rows.

source_inventory()[source]¶

Report every BindingSourceKind the committed registry declares, and where.

Walks every committed modelo revision and every binding it declares, grouping by the binding’s source kind. The result records, per source kind, the committed revisions that declare it and the per-revision binding count. This is a pure registry introspection surface — it does not consult the live calculation mesh — so it stays inside the domain boundary. Application-layer conformance compares this live inventory directly with executable calculation-route ownership so an unrouted declaration is refused rather than silently blanked.

Return type:: RegistrySourceInventoryReport
Returns:: A RegistrySourceInventoryReport whose rows are sorted by the source kind’s string value; each row’s sites are sorted by (modelo, revision_id).

support_matrix()[source]¶

Return the registry-wide per-modelo support/capability matrix.

For every modelo the authority can load, builds a ModeloEntry capturing supported revisions, calc/manifest/export/extractor capability flags, declared per-ejercicio casilla renames, declared deprecation (support-removal) decisions, and declared AEAT-portal cross-references — every field read or folded directly from the loaded registry, never hand-maintained (see aeat-calculation-aggregation / no-silent-under-declaration).

Return type:: ModeloSupportMatrixReport
Returns:: A ModeloSupportMatrixReport whose entries are sorted by modelo_id.

describe_modelo(modelo, *, period=None, as_of=None)[source]¶

Return a full describe report for one modelo and its resolved revision.

Resolves the revision using the same precedence logic as the other query methods: when period is a bare registry token (e.g. "1T", "0A"), the revision that declares it is selected; when period is None, the latest revision by valid_from is returned. Use describe_modelo_for_scope when the filing year must participate in revision selection.

Parameters:

modelo (str) – Short numeric identifier for the modelo (e.g. "303").
period (str | None) – Optional period narrowing. Accepted forms are bare registry period tokens ("1T", "0A", "01"-"12") or declared non-date tokens such as "alta".
as_of (date | None) – Optional calendar date for validity gating. Defaults to today when None.

Return type:

ModeloDescribeReport

Returns:

A ModeloDescribeReport for the resolved revision.

Raises:

RegistryValidationError – When modelo is not registered, the period is not declared by any revision, or no revision covers the requested scope.

describe_modelo_for_scope(modelo, *, filing_year, period, as_of=None)[source]¶

Return a ModeloDescribeReport for a scope.

Return type:

ModeloDescribeReport

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)

casillas(modelo, *, period=None, as_of=None, input_kind=None, required=None, form_number=None)[source]¶

Return the casilla (numbered-box) listing for a resolved modelo revision.

A casilla is a numbered input box on an AEAT tax form. The listing includes every casilla in the resolved revision, optionally filtered to a subset by kind, required flag, or form page number.

Parameters:

modelo (str) – Short numeric identifier for the modelo (e.g. "303").
period (str | None) – Optional period narrowing; see describe_modelo for accepted forms.
as_of (date | None) – Optional calendar date for validity gating.
input_kind (InputKind | None) – When supplied, restricts rows to casillas of the given InputKind (e.g. InputKind.MANUAL, InputKind.COMPUTED).
required (bool | None) – When supplied, restricts rows to casillas whose required flag matches this value.
form_number (str | None) – When supplied, restricts rows to casillas on the given physical form page or sub-form.

Return type:

ModeloCasillasReport

Returns:

A ModeloCasillasReport for the resolved revision, containing the filtered casilla rows.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.

casillas_for_scope(modelo, *, filing_year, period, as_of=None, input_kind=None, required=None, form_number=None)[source]¶

Return a ModeloCasillasReport for a scope.

Return type:

ModeloCasillasReport

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)
input_kind (InputKind | None)
required (bool | None)
form_number (str | None)

casilla(modelo, casilla, *, period=None, as_of=None)[source]¶

Return the full semantic detail for one casilla on a resolved revision.

Addresses a single casilla by its canonical id or its printed number and surfaces the authoritative label, legal/source grounding, input kind, and — when the casilla is computed — the resolved formula expression. Revision selection follows the same precedence as describe_modelo().

Parameters:

modelo (str) – Short numeric identifier for the modelo (e.g. "303").
casilla (str) – Casilla id or printed number to look up.
period (str | None) – Optional period narrowing; see describe_modelo().
as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloCasillaDetailReport

Returns:

A ModeloCasillaDetailReport for the addressed casilla.

Raises:

RegistryValidationError – When the modelo or period is not registered, no revision covers the requested scope, or the casilla id/number is not defined by the resolved revision.

casilla_for_scope(modelo, casilla, *, filing_year, period, as_of=None)[source]¶

Return a ModeloCasillaDetailReport for a scope.

Return type:

ModeloCasillaDetailReport

Parameters:

modelo (str)
casilla (str)
filing_year (int)
period (str)
as_of (date | None)

bindings_for_scope(modelo, *, filing_year, period, as_of=None)[source]¶

Return bindings for a specific filing scope (already-parsed year + period).

Unlike bindings, this method accepts the already-parsed filing_year integer and registry period string (e.g. "1T", "01") produced by the CLI’s period-parsing step. This avoids re-parsing a user-facing period string when the caller already holds the decomposed values.

Return type:

ModeloBindingsReport

Returns:

A ModeloBindingsReport for the requested filing scope.

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)

bindings_for_year(modelo, *, filing_year, as_of=None)[source]¶

Return revision-wide bindings for one filing year and effective date.

Return type:

ModeloBindingsReport

Parameters:

modelo (str)
filing_year (int)
as_of (date | None)

formulas_for_scope(modelo, *, filing_year, period, as_of=None)[source]¶

Return a ModeloFormulasReport for a scope.

Return type:

ModeloFormulasReport

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)

bindings(modelo, *, period=None, as_of=None)[source]¶

Return the full binding listing for a resolved modelo revision.

A binding maps a financial-data source to a casilla or formula input. For year-specific binding ids (e.g. when a multi-revision modelo publishes different binding names per renta year) prefer bindings_for_scope so the resolved revision matches the one the calculation engine will use.

Parameters:

modelo (str) – Short numeric identifier for the modelo (e.g. "130").
period (str | None) – Optional period narrowing; see describe_modelo for accepted forms. When None, the latest revision is used.
as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloBindingsReport

Returns:

A ModeloBindingsReport for the resolved revision.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.

formulas(modelo, *, period=None, as_of=None)[source]¶

Return the full formula listing for a resolved modelo revision.

Each row exposes one formula’s target_casilla_id and its complete input dependency set (casillas, bindings, parameters, and relation references), letting contributors inspect what drives a computed casilla without reading the raw registry TOML.

Parameters:

modelo (str) – Short numeric identifier for the modelo (e.g. "200").
period (str | None) – Optional period narrowing; see describe_modelo for accepted forms. When None, the latest revision is used.
as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloFormulasReport

Returns:

A ModeloFormulasReport for the resolved revision.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.

resolve_revision_for_scope(modelo, *, filing_year, period, as_of, grade=RegistryAuthorityGrade.APPLICABILITY)[source]¶

Resolve the unique revision governing one explicit filing scope.

Return type:

ResolvedRegistryQueryContext

Parameters:

modelo (str)
filing_year (int)
period (str)
as_of (date | None)
grade (RegistryAuthorityGrade)

class PinnedRegistryQueryService(operation)[source]¶

Bases: object

Report facade over one generation-pinned component operation.

The legacy RegistryQueryService remains the explicit eager diagnostic facade. Application discovery uses this point-loaded variant: selector-complete directories provide metadata and each report hydrates only the revision selected for that query.

Parameters:: operation (PinnedAuthorityOperation)

modelo_codes()[source]¶

Return deterministic model identities from the pinned index.

Return type:: tuple[str, ...]

iter_modelo_revisions(*, modelo_codes=None)[source]¶

Explicitly enumerate point-loaded revisions for diagnostics.

Return type:: tuple[tuple[str, ModeloRevision], ...]
Parameters:: modelo_codes (tuple[str, ...] | None)

iter_modelo_definitions()[source]¶

Materialize one latest revision view per modelo for diagnostics.

Return type:: tuple[ModeloDefinition, ...]

list_modelos(*, year=None, domain=None)[source]¶

Return a metadata catalogue read from the modelo directories alone.

Every listed field is modelo-level metadata the directory carries, and revision count and year coverage come from its complete revision metadata, so no revision payload is decoded.

Return type:

ModeloListReport

Parameters: