"""Typed report contracts for registry query surfaces.
These frozen pydantic DTOs are emitted by
:class:`~domain.calculations.registry.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
:class:`~core.BindingSourceKind` declarations and leaves enrolled/deferred/
reserved mesh classification to application-layer gates.
See Also:
:class:`~domain.calculations.registry.RegistryQueryService`
Builder of every report class defined here.
:mod:`~application.modelo._registry_discovery`
Application facade used by CLI discovery commands.
:mod:`~entrypoints.cli._modelo_discovery_cli`
Typer command group that renders these reports to text and JSON.
:mod:`~entrypoints.cli._modelo_payloads`
CLI-side ``OutputSchema`` projections for discovery command envelopes.
:class:`~domain.calculations.registry.ModeloRevision`
Revision record from which casilla, binding, and formula rows are
projected.
:class:`~domain.calculations.registry._support_matrix.ModeloEntry`
Support-matrix row carried by :class:`ModeloSupportMatrixReport`.
"""
from __future__ import annotations
from collections.abc import Mapping
from datetime import date
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
from ....core import BindingSourceKind, Period
from ._binding_selector_utils import BooleanBindingEncodedValue
from ._ids import BindingId, CasillaId, FormulaId, LegalRefId, ParameterId, RelationId, SourceRefId
from ._schema_input_kind import InputKind
from ._support_matrix import ModeloEntry
[docs]
class ModeloListRow(BaseModel):
"""One entry in a modelo catalogue listing."""
model_config = ConfigDict(frozen=True)
code: str
title: str
cadence: str
tax_domain: str
revision_count: int
[docs]
class ModeloListReport(BaseModel):
"""Complete result set for a modelo catalogue query."""
model_config = ConfigDict(frozen=True)
modelos: tuple[ModeloListRow, ...]
[docs]
class ModeloDescribeReport(BaseModel):
"""Full describe view for one resolved modelo revision."""
model_config = ConfigDict(frozen=True)
code: str
title: str
official_name: str
tax_domain: str
cadence: str
jurisdiction: str
revision: str
revision_ids: tuple[str, ...]
filing_year: int | None
filing_period: Period | None = None
period: str | None
valid_from: date
valid_to: date | None
periods: tuple[str, ...]
casilla_count: int
manual_casilla_count: int
bound_casilla_count: int
computed_casilla_count: int
binding_count: int
formula_count: int
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
[docs]
class ModeloCasillaRow(BaseModel):
"""One row in a casilla listing for a resolved modelo revision."""
model_config = ConfigDict(frozen=True)
casilla_id: CasillaId
number: str
label: str
section: tuple[str, ...]
data_type: str
input_kind: InputKind
required: bool
formula: str | None
binding: BindingId | None
form_number: str | None
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
localized_labels: dict[str, str] = Field(default_factory=dict)
localized_help: dict[str, str] = Field(default_factory=dict)
[docs]
class ModeloCasillasReport(BaseModel):
"""Full casilla listing for a resolved modelo revision."""
model_config = ConfigDict(frozen=True)
code: str
revision: str
filing_year: int | None
filing_period: Period | None = None
period: str | None
rows: tuple[ModeloCasillaRow, ...]
[docs]
class ModeloCasillaDetailReport(BaseModel):
"""Full semantic detail for one casilla on a resolved modelo revision."""
model_config = ConfigDict(frozen=True)
code: str
revision: str
filing_year: int | None
filing_period: Period | None = None
period: str | None
casilla_id: CasillaId
number: str
label: str
localized_labels: dict[str, str] = Field(default_factory=dict)
localized_help: dict[str, str] = Field(default_factory=dict)
section: tuple[str, ...]
data_type: str
input_kind: InputKind
required: bool
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
binding: BindingId | None
formula_id: FormulaId | None
formula_expression: Mapping[str, object] | None
BindingSelectorQueryValue = str | int | bool | tuple[str, ...]
[docs]
class BindingSelectorQueryEntry(BaseModel):
"""One normalized binding-selector entry on the public query surface."""
model_config = ConfigDict(frozen=True, extra="forbid")
key: str = Field(min_length=1)
value: BindingSelectorQueryValue
[docs]
class BindingSelectorQueryProjection(BaseModel):
"""Typed public projection of a binding selector."""
model_config = ConfigDict(frozen=True, extra="forbid")
source: str
keys: tuple[str, ...]
entries: tuple[BindingSelectorQueryEntry, ...]
[docs]
class ModeloBindingQueryRow(BaseModel):
"""One row in a binding listing for a resolved modelo revision."""
model_config = ConfigDict(frozen=True)
binding_id: BindingId
source: str
typed_enum: str | None
input_channel: Literal["decimal", "enum"]
selector: BindingSelectorQueryProjection
aggregation: Mapping[str, object] | None
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
borrador_capable: bool = False
relation_inputs: tuple[RelationId, ...] = ()
encoded_options: tuple[BooleanBindingEncodedValue, ...] = ()
operator_input_required: bool = True
[docs]
class ModeloBindingsReport(BaseModel):
"""Full binding listing for a single resolved modelo revision."""
model_config = ConfigDict(frozen=True)
code: str
revision: str
filing_year: int | None
filing_period: Period | None = None
period: str | None
rows: tuple[ModeloBindingQueryRow, ...]
[docs]
class RegistrySourceSite(BaseModel):
"""One committed modelo revision that declares a binding source kind."""
model_config = ConfigDict(frozen=True)
modelo: str
revision_id: str
binding_count: int = Field(ge=1)
[docs]
class RegistrySourceInventoryRow(BaseModel):
"""Every committed revision that declares one binding source kind."""
model_config = ConfigDict(frozen=True)
source_kind: BindingSourceKind
sites: tuple[RegistrySourceSite, ...]
total_binding_count: int = Field(ge=1)
[docs]
class RegistrySourceInventoryReport(BaseModel):
"""Registry-wide inventory of every declared binding source kind."""
model_config = ConfigDict(frozen=True)
rows: tuple[RegistrySourceInventoryRow, ...]
@property
def declared_source_kinds(self) -> frozenset[BindingSourceKind]:
"""The set of binding source kinds the registry declares."""
return frozenset(row.source_kind for row in self.rows)
[docs]
class ModeloSupportMatrixReport(BaseModel):
"""Registry-wide support/capability matrix."""
model_config = ConfigDict(frozen=True)
entries: tuple[ModeloEntry, ...]
__all__ = [
"BindingSelectorQueryEntry",
"BindingSelectorQueryProjection",
"BindingSelectorQueryValue",
"ModeloBindingQueryRow",
"ModeloBindingsReport",
"ModeloCasillaDetailReport",
"ModeloCasillaRow",
"ModeloCasillasReport",
"ModeloDescribeReport",
"ModeloFormulaRow",
"ModeloFormulasReport",
"ModeloListReport",
"ModeloListRow",
"ModeloSupportMatrixReport",
"RegistrySourceInventoryReport",
"RegistrySourceInventoryRow",
"RegistrySourceSite",
]