cadrumo.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().

This module is the production entry point through which callers (CLI, workflow, services) construct profiles and schema providers.

Key entry points:

ModeloOperatorProfile — pydantic v2 record satisfying the filing-profile Protocol.
filing_profile_from_taxpayer() — projects taxpayer identity from a domain TaxpayerProfile into the runtime profile shape without deriving legal filing obligations.
build_runtime_schema_provider() — requires registry-backed snapshots.
schema_provider_from_authority() — projects an explicitly supplied validated authority through the same provider surface.

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.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:

data (Any)

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, complete CasillaConstraints contract and regulatory grounding (legal_refs, source_refs) from the authoritative CasillaDefinition.

Parameters:: data (Any)

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, ...]¶

constraints: CasillaConstraints | 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)

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 ordered by canonical casilla_id.

Deliberately not registry declaration order: the loader compiles revision.casillas in casilla-fragment filename order, so declaration order tracks the corpus layout rather than anything the filing surface should depend on. collection_from_snapshot() sorts by canonical id so this projection stays stable under a fragment rename.

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=(), rate_box_partitions=(), profile_export_bindings=())[source]¶

Bases: object

Snapshot-backed filing details for one modelo revision.

Parameters:

modelo_id (str)
revision_id (RevisionId)
schema_version (str)
cadence (str)
period_selector_periods (tuple[str, ...])
legal_ref_ids (tuple[LegalRefId, ...])
source_ref_ids (tuple[SourceRefId, ...])
extraction_profile_ids (tuple[str, ...])
verification_expectation_ids (tuple[str, ...])
reconciliation_total_casilla_ids (Mapping[Annotated[SettlementDirection, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)], CasillaId])
export_layout_ids (tuple[str, ...])
export_layouts (tuple[ExportLayoutDefinition, ...])
application_link_ids (tuple[str, ...])
deadline_window_ids (tuple[str, ...])
completeness_manifest (CalculationCompletenessManifest | None)
casilla_record_metadata (tuple[CasillaRecordMetadata, ...])
rate_box_partitions (tuple[RateBoxPartition, ...])
profile_export_bindings (tuple[BindingDefinition, ...])

modelo_id: str¶

revision_id: TypeAliasType¶

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[Annotated[SettlementDirection], TypeAliasType]¶

export_layout_ids: tuple[str, ...]¶

export_layouts: tuple[ExportLayoutDefinition, ...]¶

application_link_ids: tuple[str, ...]¶

deadline_window_ids: tuple[str, ...]¶

completeness_manifest: CalculationCompletenessManifest | None¶

casilla_record_metadata: tuple[CasillaRecordMetadata, ...]¶

rate_box_partitions: tuple[RateBoxPartition, ...]¶

one rate-blind total casilla and the rate-specific casillas that break it down.

A derivation, not a second copy of the binding set: the whole ledger-IVA binding tuple would make this a shadow snapshot, so what is carried is only the pairing the export gate needs. The gate refuses a return whose rate boxes account for less than their total, and it cannot re-derive the pairing itself without a revision it does not hold.

Empty for every revision declaring no rate-specific binding, which is every revision until a modelo splits a tier casilla into its box and total layers.

Type:: Two-layer rate partitions the revision declares

profile_export_bindings: tuple[BindingDefinition, ...]¶

Profile bindings that declare an address on the exported record.

Deliberately NOT every profile binding: only those carrying a dictionary_field, which is what makes a binding addressable on the exported declaration. A subview carrying the whole binding set would stop being a projection and start being a second snapshot, which is the shape the registry authority owns and this class must not duplicate.

The export header composer reads these to populate the identity slots AEAT’s dictionary names, so the join is driven by the registry’s own declarations rather than by a hand-written map per field.

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, snapshots, sources=<factory>, evidence=<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 (Mapping[str, RegistryCasillaCollection])
subviews (Mapping[str, RegistryModeloSubview])
snapshots (Mapping[str, RegistrySnapshot])
sources (Mapping[SourceRefId, SourceReference])
evidence (AuthorityEvidenceProjection)

collections: Mapping[str, RegistryCasillaCollection]¶

subviews: Mapping[str, RegistryModeloSubview]¶

snapshots: Mapping[str, RegistrySnapshot]¶

sources: Mapping[TypeAliasType, SourceReference]¶

evidence: AuthorityEvidenceProjection¶

source_payload(source_ref_id)[source]¶

Return published authority bytes for one runtime source reference.

Return type:: bytes
Parameters:: source_ref_id (SourceRefId)

property source_payloads: Mapping[str, bytes]¶: Expose the immutable signed source projection for layout consumers.

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)

get_snapshot(modelo)[source]¶

Return the exact immutable registry snapshot selected for modelo.

Return type:: RegistrySnapshot
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.

build_runtime_schema_provider(*, filing_year, period, modelos=None, operation=None)[source]¶

Build a RegistrySchemaAccessor from validated snapshots.

filing_year and period are required and period must be a typed Period; raw registry tokens are rejected before snapshot lookup.

The provider has no registry or source-root override: filing flows consume the immutable authority bundled with the installed package.

Parameters:

filing_year (int) – Filing year of the draft or request.
period (object) – Typed Period matching filing_year.
modelos (Sequence[str] | None) – Optional modelo id selection. Blank ids are rejected.
operation (PinnedAuthorityOperation | None) – Optional generation-pinned indexed authority operation. When supplied, modelos must name the requested models explicitly and snapshots are loaded through point revision/directory access.

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.

schema_provider_from_authority(authority, *, filing_year, period, modelos=None, operation=None)[source]¶

Build a RegistrySchemaAccessor from an explicit validated authority.

Applies the same period validation, modelo selection and snapshot projection as build_runtime_schema_provider(), which delegates here with the bundled authority. Callers that hold a separately compiled authority (for example a development build of the registry source tree) use this entry point to project it through the identical filing surface.

Parameters:

authority (ValidatedRegistryAuthority) – Validated registry authority to project.
filing_year (int) – Filing year of the draft or request.
period (object) – Typed Period matching filing_year.
modelos (Sequence[str] | None) – Optional modelo id selection. Blank ids are rejected.
operation (PinnedAuthorityOperation | None) – Optional generation-pinned indexed authority operation. When supplied, it takes precedence over the eager authority for the selected model point loads.

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.

Core types: ValidatedRegistryAuthority.

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.

subview_from_snapshot(snapshot)[source]¶

Project a validated snapshot into the modelo subview the filing handoff carries.

Core types: RegistrySnapshot.

Return type:: RegistryModeloSubview
Parameters:: snapshot (RegistrySnapshot)

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.protocols.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)