aeat.application.filing.runtime module

Production runtime helpers for application.filing.

Exposes concrete profile helpers used by the CLI and workflow surfaces. The production schema provider requires validated registry snapshots and projects them into the CasillaSchemaProvider surface consumed by build_draft().

The filing runtime must not depend on application.filing.testing; this module is the production entry point that callers (CLI, workflow, services) construct profiles and schema providers through.

Key entry points:

The schema provider consumes a RegistrySnapshot built from a ModeloRevision within a ModeloDefinition, accessed through a ValidatedRegistryAuthority loaded from the configured registry root.

See also

application.wizard._status.load_active_taxpayer_profile()

Active-profile bridge that supplies the domain.deadlines.TaxpayerProfile projected here.

application.modelo._workflow_gate

Calculation-revision workflow gate that uses this runtime provider to build and approve filing drafts.

application.modelo._revision_replay_inputs

Converts stored calculation revisions into the flat filing inputs accepted by this runtime surface.

class TaxpayerProfileIdentity(*args, **kwargs)[source]

Bases: Protocol

Structural identity surface accepted by the filing profile projector.

property tax_id: SubjectTaxId

Validated tax identity copied into the filing runtime profile.

class ModeloOperatorProfile(**data)[source]

Bases: BaseModel

Concrete runtime implementation of the filing-profile Protocol.

Strict, frozen pydantic v2 model satisfying the filing layer’s profile Protocol.

Variables:

  • tax_id – Validated NIF / NIE / CIF of the filing operator.

  • display_name – Human-readable label for the profile.

Parameters:

  • tax_id (SubjectTaxId)

  • display_name (str)

tax_id: SubjectTaxId
display_name: str
class RegistryCasillaSchema(**data)[source]

Bases: BaseModel

Filing schema projection for one registry casilla.

Strict, frozen pydantic v2 projection preserving typed IDs, Decimal bounds, and the regulatory grounding (legal_refs, source_refs) from the authoritative CasillaDefinition.

Parameters:

  • casilla_id (CasillaId)

  • value_type (str)

  • required (bool)

  • formula (FormulaId | None)

  • formula_input_casilla_ids (tuple[CasillaId, ...])

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

  • min_value (Decimal | None)

  • max_value (Decimal | None)

  • default (object | None)

casilla_id: CasillaId
value_type: str
required: bool
formula: FormulaId | None
formula_input_casilla_ids: tuple[CasillaId, ...]
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
min_value: Decimal | None
max_value: Decimal | None
default: object | None
class RegistryCasillaCollection(casillas, schema_version)[source]

Bases: object

Filing schema collection projected from one modelo registry definition.

Parameters:
casillas: tuple[RegistryCasillaSchema, ...]
schema_version: str
get(casilla_id)[source]

Return the CasillaSchema for casilla_id, or None if absent.

Return type:

CasillaSchema | None

Parameters:

casilla_id (CasillaId)

all()[source]

Return all casilla schemas in declaration order.

Each element is a CasillaSchema.

Return type:

Sequence[CasillaSchema]

class CasillaRecordMetadata(casilla_id, number, segmento)[source]

Bases: object

Registry-declared official record-design metadata for one casilla.

Projected verbatim from the authoritative CasillaDefinition — the same authority the calculation engine consumes — so the fichero-BOE export parity gate can re-ground the rendered casilla’s number and segmento against the registry declaration at the render choke point rather than trusting the completeness manifest’s own copy of that metadata.

Variables:

  • casilla_id – Canonical registry casilla identity.

  • number – AEAT record-design casilla number.

  • segmento – AEAT record-segment code for multi-segment modelos, or None for single-segment modelos.

Parameters:

  • casilla_id (CasillaId)

  • number (str)

  • segmento (str | None)

casilla_id: TypeAliasType
number: str
segmento: str | None
class RegistryModeloSubview(modelo_id, revision_id, schema_version, cadence, period_selector_periods, legal_ref_ids, source_ref_ids, extraction_profile_ids, verification_expectation_ids, reconciliation_total_casilla_ids, export_layout_ids, export_layouts, application_link_ids, deadline_window_ids, completeness_manifest, casilla_record_metadata=())[source]

Bases: object

Snapshot-backed filing details for one modelo revision.

Parameters:
modelo_id: str
revision_id: str
schema_version: str
cadence: str
period_selector_periods: tuple[str, ...]
legal_ref_ids: tuple[TypeAliasType, ...]
source_ref_ids: tuple[TypeAliasType, ...]
extraction_profile_ids: tuple[str, ...]
verification_expectation_ids: tuple[str, ...]
reconciliation_total_casilla_ids: Mapping[Literal['ingresar', 'devolver'], TypeAliasType]
export_layout_ids: tuple[str, ...]
export_layouts: tuple[ExportLayoutDefinition, ...]
deadline_window_ids: tuple[str, ...]
completeness_manifest: CalculationCompletenessManifest | None
casilla_record_metadata: tuple[CasillaRecordMetadata, ...]
has_completeness_manifest()[source]

Return whether this revision carries a calculation-completeness manifest.

The manifest is the AEAT Diseño de Registros calculation-closure projection (CalculationCompletenessManifest) that grounds the fichero-BOE export parity gate. A revision without one cannot have its .boe export checked for casilla completeness, so the export path surfaces a coverage advisory rather than asserting parity.

Return type:

bool

class RegistrySchemaAccessor(collections, subviews, source_root=None, sources=<factory>)[source]

Bases: object

Registry-backed filing schema accessor.

The concrete registry-schema accessor (it provides casilla collections and modelo subviews from validated registry TOML); structurally satisfies the CasillaSchemaProvider protocol. Named an accessor to stay distinct from the settled calculate-mesh resolver port.

Parameters:
collections: dict[str, RegistryCasillaCollection]
subviews: dict[str, RegistryModeloSubview]
source_root: Path | None
sources: Mapping[TypeAliasType, SourceReference]
get_collection(modelo)[source]

Return the casilla collection for modelo.

Returns a CasillaCollection for the modelo. Raises ModeloBuilderError when the modelo is absent.

Return type:

CasillaCollection

Parameters:

modelo (str)

get_subview(modelo)[source]

Return the RegistryModeloSubview backing modelo.

Return type:

RegistryModeloSubview

Parameters:

modelo (str)

filing_profile_from_taxpayer(profile, *, display_name=None)[source]

Project taxpayer identity into a ModeloOperatorProfile.

The common caller passes TaxpayerProfile, but the accepted contract is the narrower TaxpayerProfileIdentity Protocol. This helper deliberately copies only taxpayer identity. Modelo applicability is legal filing truth and must come from validated registry data, not a filing-runtime tuple or the deadline engine.

Parameters:

  • profile (TaxpayerProfileIdentity) – Source identity object exposing tax_id.

  • display_name (str | None) – Optional friendly label; defaults to profile.tax_id.

Return type:

ModeloOperatorProfile

Returns:

A frozen ModeloOperatorProfile.

load_default_filing_profile(*, display_name=None)[source]

Load the active profile bucket for runtime filing commands.

Resolves the active workflow profile via the wizard descriptor’s typed projection and re-shapes it as a runtime ModeloOperatorProfile. Operator profile values stored in the profile bucket are the single source of truth.

Parameters:

display_name (str | None) – Optional friendly label propagated to the returned profile.

Return type:

ModeloOperatorProfile

Returns:

The loaded ModeloOperatorProfile.

Raises:

ModeloBuilderError – When no profile is active in the workflow state.

build_runtime_schema_provider(registry_root=None, *, source_root=None, filing_year=None, period=None, modelos=None)[source]

Build a RegistrySchemaAccessor from validated registry TOML.

When filing_year and period are supplied, both are required and period must be a typed Period; raw registry tokens are rejected before snapshot lookup. Without an explicit period, the provider selects the current open revision for each modelo.

Parameters:

  • registry_root (Path | None) – Optional registry root. Defaults to the bundled AEAT registry.

  • source_root (Path | None) – Optional source-material root used by ValidatedRegistryAuthority.

  • filing_year (int | None) – Optional filing year; must be paired with period.

  • period (object | None) – Optional typed Period; must match filing_year.

  • modelos (Sequence[str] | None) – Optional modelo id selection. Blank ids are rejected.

Return type:

RegistrySchemaAccessor

Returns:

A RegistrySchemaAccessor implementing the filing CasillaSchemaProvider surface.

Raises:

ModeloBuilderError – When the registry is empty, a requested modelo is missing, the period arguments are invalid, or no snapshot exists for the requested filing context.

clear_runtime_fingerprint_cache()[source]

Clear the time-based TTL cache for registry tree fingerprints.

Return type:

None

registry_tree_fingerprint(root)[source]

Return the TTL-cached registry tree fingerprint for runtime schema loading.

The fingerprint covers legal and modelos TOML files under root and is keyed by relative path, mtime, and size. It is used as a cache key for build_runtime_schema_provider(); call clear_runtime_fingerprint_cache() when tests or tooling mutate the registry tree inside the one-second TTL.

Return type:

tuple[tuple[str, int, int], ...]

Parameters:

root (Path)

collection_from_snapshot(snapshot)[source]

Project a validated registry snapshot into a runtime casilla collection.

Parameters:

snapshot (RegistrySnapshot) – The RegistrySnapshot whose ModeloRevision is projected into filing-runtime casilla schemas.

Return type:

RegistryCasillaCollection

Returns:

A RegistryCasillaCollection with the snapshot revision’s casillas and registry:{modelo}:{revision} schema version.

Raises:

ModeloBuilderError – When the snapshot revision contains ambiguous casilla references and cannot be projected safely.

registry_value_type(data_type)[source]

Map a registry casilla data type to the filing runtime value type.

Returns one of the value-type tags consumed by domain.filing.CasillaSchema: "decimal", "int", "str", "bool", or "date".

Raises:

ModeloBuilderError – When data_type is not a supported registry casilla type.

Return type:

str

Parameters:

data_type (str)