cadrumo.domain.calculations.registry.query_reports module

Typed report contracts for registry query surfaces.

These frozen pydantic DTOs are emitted by RegistryQueryService for read-only registry introspection: modelo listings, revision descriptions, casilla details, binding selector projections, formula dependency rows, support-matrix summaries, and the registry-wide binding-source inventory.

The contracts stay in the domain layer and are deliberately not CLI payload schemas. Application facades return these reports unchanged; CLI modules then project them into strict --json envelopes. The source-inventory report is also intentionally disposition-free: it records the committed BindingSourceKind declarations and leaves enrolled/deferred/ reserved mesh classification to application-layer gates.

See also

RegistryQueryService

Builder of every report class defined here.

registry_discovery

Application facade used by CLI discovery commands.

_modelo_discovery_cli

Typer command group that renders these reports to text and JSON.

_modelo_payloads

CLI-side OutputSchema projections for discovery command envelopes.

ModeloRevision

Revision record from which casilla, binding, and formula rows are projected.

ModeloEntry

Support-matrix row carried by ModeloSupportMatrixReport.

class BindingInputChannel(*values)[source]

Bases: StrEnum

How a binding receives its value from the operator surface.

DECIMAL
ENUM
BindingInputChannelValue

The same vocabulary for a strict model field.

alias of Literal[DECIMAL, ENUM]

class ModeloListRow(**data)[source]

Bases: BaseModel

One entry in a modelo catalogue listing.

Parameters:

data (Any)

code: str
title: str
cadence: str
tax_domain: str
revision_count: int
class ModeloListReport(**data)[source]

Bases: BaseModel

Complete result set for a modelo catalogue query.

Parameters:

data (Any)

modelos: tuple[ModeloListRow, ...]
class ModeloDescribeReport(**data)[source]

Bases: BaseModel

Full describe view for one resolved modelo revision.

Every field here is regulatory grounding an operator may need to justify a revision selection, so the counts are bounded and filing_year shares the Period year range: a describe view is projected verbatim into the CLI --json envelope, and a negative count or an out-of-range year reaching that surface is a defect in the projection, not a legitimate value.

Parameters:

data (Any)

code: str
title: str
official_name: str
tax_domain: str
cadence: str
jurisdiction: str
revision: str
revision_ids: tuple[str, ...]
filing_year: FilingYear | None
filing_period: Period | None
period: RegistrySelectorPeriodCode | None
valid_from: date
valid_to: date | None
periods: tuple[str, ...]
casilla_count: NonNegativeInt
manual_casilla_count: NonNegativeInt
bound_casilla_count: NonNegativeInt
computed_casilla_count: NonNegativeInt
binding_count: NonNegativeInt
formula_count: NonNegativeInt
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class CasillaGroundingReport(**data)[source]

Bases: BaseModel

Semantic identity and regulatory grounding of one casilla.

The casilla list row and the casilla detail report describe the same casilla. Everything a reader needs to identify it and to justify its value – its id, number, label, section path, value shape, input kind, requiredness, its bound binding, its localized label/help, and its legal_refs / source_refs grounding – is declared once here, so the two projections cannot disagree about the same casilla.

Before this base existed the list row typed its references as unconstrained tuple[str, ...] while the detail report used the canonical LegalRefId / SourceRefId, so a reference shape the detail projection refused passed silently through operator list JSON.

Subclasses add only what genuinely differs: the resolved formula reference and form number for a listing row, the query context and full formula expression for a detail view.

Parameters:

data (Any)

casilla_id: CasillaId
number: str
label: str
help_text: str | None
section: tuple[str, ...]
data_type: str
input_kind: InputKind
required: bool
binding: BindingId | None
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class ModeloCasillaRow(**data)[source]

Bases: CasillaGroundingReport

One row in a casilla listing for a resolved modelo revision.

Adds the listing-shaped formula reference and the official form number to the shared CasillaGroundingReport identity and grounding.

Parameters:
formula: str | None
form_number: AeatBoxNumber | None
class ModeloCasillasReport(**data)[source]

Bases: BaseModel

Full casilla listing for a resolved modelo revision.

Parameters:

data (Any)

code: str
revision: str
filing_year: int | None
filing_period: Period | None
period: RegistrySelectorPeriodCode | None
rows: tuple[ModeloCasillaRow, ...]
class ModeloCasillaDetailReport(**data)[source]

Bases: CasillaGroundingReport

Full semantic detail for one casilla on a resolved modelo revision.

Adds the resolving query context and the full formula reference plus its expression to the shared CasillaGroundingReport identity and grounding.

Parameters:
code: str
revision: str
filing_year: int | None
filing_period: Period | None
period: RegistrySelectorPeriodCode | None
formula_id: FormulaId | None
formula_expression: Mapping[str, object] | None
class ModeloBindingQueryRow(**data)[source]

Bases: BaseModel

One row in a binding listing for a resolved modelo revision.

Parameters:

data (Any)

binding_id: BindingId
typed_enum: str | None
input_channel: BindingInputChannelValue
provider: BindingProvider

The binding’s own provider union member, carried whole.

The public surface used to flatten the declaration into an untagged key/value entry list, which erased the member’s identity and its field types. Carrying the member itself keeps the discriminator and every typed field; a JSON consumer serialises it with model_dump(mode="json").

aggregation: Mapping[str, object] | None
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
borrador_capable: bool
relation_inputs: tuple[BindingId, ...]

The fold slots feeding this row. A relation-prefill binding names ITSELF here, because the fold and the slot are one declaration; every other binding names none.

encoded_options: tuple[BooleanBindingEncodedValue, ...]
operator_input_required: bool
class ModeloBindingsReport(**data)[source]

Bases: BaseModel

Full binding listing for a single resolved modelo revision.

Parameters:

data (Any)

code: str
revision: str
filing_year: int | None
filing_period: Period | None
period: RegistrySelectorPeriodCode | None
rows: tuple[ModeloBindingQueryRow, ...]
class ModeloFormulaRow(**data)[source]

Bases: BaseModel

One row in a formula listing for a resolved modelo revision.

Parameters:

data (Any)

formula_id: FormulaId
target_casilla_id: CasillaId
input_casilla_ids: tuple[CasillaId, ...]
input_bindings: tuple[BindingId, ...]
input_parameters: tuple[ParameterId, ...]
input_relations: tuple[BindingId, ...]

The subset of input_bindings that are relation-prefill fold slots.

expression: Mapping[str, object]
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class ModeloFormulasReport(**data)[source]

Bases: BaseModel

Full formula listing for a single resolved modelo revision.

Parameters:

data (Any)

code: str
revision: str
filing_year: int | None
filing_period: Period | None
period: RegistrySelectorPeriodCode | None
rows: tuple[ModeloFormulaRow, ...]
class RegistrySourceSite(**data)[source]

Bases: BaseModel

One committed modelo revision that declares a binding source kind.

Parameters:

data (Any)

modelo: str
revision_id: RevisionId
binding_count: PositiveCount
class RegistrySourceInventoryRow(**data)[source]

Bases: BaseModel

Every committed revision that declares one binding source kind.

Parameters:

data (Any)

source_kind: BindingSourceKind
sites: tuple[RegistrySourceSite, ...]
total_binding_count: PositiveCount
class RegistrySourceInventoryReport(**data)[source]

Bases: BaseModel

Registry-wide inventory of every declared binding source kind.

Parameters:

data (Any)

rows: tuple[RegistrySourceInventoryRow, ...]
class ModeloSupportMatrixReport(**data)[source]

Bases: BaseModel

Registry-wide support/capability matrix.

Parameters:

data (Any)

entries: tuple[ModeloEntry, ...]