aeat.application.filing._export module

Typed records for the local declaration export / verify lifecycle.

The CLI exposes two primitives the application layer must back end-to-end:

  • modelo export writes an AEAT declaration file from a validated registry snapshot for an approved domain.filing.ModeloDraft and reports the byte-level summary the operator needs to track the artefact (output path, draft identity, content hash, format).

  • modelo export verification re-reads a previously exported file and confirms that its casilla payload still matches the approved draft. The verdict is a closed enum; the diff (if any) is reported as a tuple of mismatched casilla identifiers so the CLI can render a deterministic table.

The records are structured return values for renderers, persistence, and JSON round trips. Runtime export requires registry-backed domain.calculations.registry.ExportLayoutDefinition records, and verification parses payloads through domain.calculations.registry.parse_export_payload().

The records intentionally do not embed the AEAT submission lifecycle (domain.submission) — local export and live submit are separate concerns and live submit is permanently forbidden.

This module is the draft-level renderer. The work-unit export service in application.modelo._export rebuilds an approved domain.filing.ModeloDraft from a domain.modelos.CalculationRevision, then delegates here to write and verify the fichero-BOE bytes.

See also

application.modelo._export.export_modelo_revision()

Higher-level work-unit export service that replays a calculation revision before calling this draft renderer.

adapters.outbound.aeat.export

Outbound export-format adapter errors and fixed-width helper namespace.

core.access_gate.LiveSubmitForbiddenError

Core refusal raised for every attempted live AEAT write.

domain.submission

Local-only submitted-state lifecycle, separate from file export.

class DeclaracionExportFormat(*values)[source]

Bases: StrEnum

Closed catalogue of AEAT export formats.

Variables:

FICHERO_BOE – Fixed-width “importar datos” payload defined by the AEAT Diseño de registros per modelo and validated through the registry.

FICHERO_BOE
XML_DICTIONARY
class DeclaracionVerifyVerdict(*values)[source]

Bases: StrEnum

Closed verdict the verify command surfaces to the operator.

Variables:

  • MATCH – Every parser-covered casilla in the file equals the approved draft’s casilla value. Check DeclaracionVerifyResult.unchecked_casilla_ids for draft casillas that the registry parser cannot re-read from the wire layout.

  • DRIFT – At least one casilla diverges between the file and the approved draft. The CLI renders the per-casilla diff.

  • MISSING – The file is unreadable, malformed, or does not cover the casillas the draft declares. No diff is computed.

MATCH
DRIFT
MISSING
class DeclaracionExportResult(**data)[source]

Bases: BaseModel

Receipt produced by exporting an approved draft to disk.

The record is the structured-data return value of the modelo export command. It carries enough metadata for the operator to identify the artefact later, for the verify command to anchor its comparison, and for the audit log to record the export event without re-reading the file.

Variables:

  • draft_id – The domain.filing.ModeloDraft identity the export was generated from.

  • modelo – AEAT modelo identifier.

  • period – Typed filing period for the exported draft.

  • format – The on-disk wire format (closed DeclaracionExportFormat).

  • output_path – Absolute path the file was written to.

  • byte_size – Size of the written content in bytes; matches output_path.stat().st_size at write time.

  • file_sha256 – Hex-encoded SHA-256 digest of the written bytes. Used by DeclaracionVerifyResult to anchor the file-vs-draft comparison.

  • exported_at – UTC timestamp of when the file was written.

  • narrative – Translation key for operator-facing summary.

  • casilla_provenance – Regulatory grounding for the draft casillas represented by the selected registry export layout.

Parameters:

See also

DeclaracionVerifyResult

Verification record that re-reads the exported bytes and anchors the comparison by file_sha256.

domain.calculations.registry.ExportLayoutDefinition

Registry layout used to render the fixed-width payload.

draft_id: str
modelo: str
period: Period
format: DeclaracionExportFormat
output_path: Path
byte_size: int
file_sha256: str
exported_at: datetime
narrative: str
casilla_provenance: tuple[ModeloCasillaProvenance, ...]
class DeclaracionVerifyResult(**data)[source]

Bases: BaseModel

Verdict produced by verifying an exported file against an approved draft.

The verify command re-reads the file the export command wrote and compares its casilla payload against the approved domain.filing.ModeloDraft. The verdict is the typed return value the CLI renders.

Variables:

  • draft_id – The domain.filing.ModeloDraft identity the file was compared against.

  • file_path – Absolute path of the file that was verified.

  • verdict – Closed DeclaracionVerifyVerdict.

  • mismatched_casilla_ids – Tuple of casilla identifiers whose value in the file differs from the approved draft. Empty when verdict is MATCH; populated when verdict is DRIFT; always empty when verdict is MISSING (the diff cannot be computed).

  • unchecked_casilla_ids – Tuple of draft casilla identifiers that do not round-trip through the export parser because the wire schema exposes them as reserved constants or derived fields rather than deserialised currency casillas.

  • file_sha256 – Hex SHA-256 of the bytes the verifier read. Lets the audit trail prove the same file the export command wrote was the one verified, even if output_path was renamed in between.

  • verified_at – UTC timestamp of when the verdict was produced.

  • narrative – Translation key for operator-facing summary.

  • casilla_provenance – Regulatory grounding for the draft casillas covered by the export parser/layout.

  • mismatched_casilla_provenance – Regulatory grounding for the subset of mismatched_casilla_ids.

Parameters:

See also

domain.calculations.registry.parse_export_payload()

Registry parser used to compute parser-covered casillas.

DeclaracionVerifyVerdict

Closed verdict enum rendered by the CLI.

DeclaracionExportResult

Export receipt whose digest anchors later verification.

draft_id: str
file_path: Path
verdict: DeclaracionVerifyVerdict
mismatched_casilla_ids: tuple[CasillaId, ...]
unchecked_casilla_ids: tuple[CasillaId, ...]
casilla_provenance: tuple[ModeloCasillaProvenance, ...]
mismatched_casilla_provenance: tuple[ModeloCasillaProvenance, ...]
file_sha256: str | None
verified_at: datetime
narrative: str
export_draft(draft, *, output_path, headers, schema_provider=None)[source]

Write an approved draft to a local fichero-BOE file and return a receipt.

The function selects the active registry ExportLayoutDefinition, renders its fixed-width records, writes only output_path, and never contacts AEAT. Live submission is outside this surface and is refused by core.access_gate.LiveSubmitForbiddenError.

Parameters:

  • draft (ModeloDraft) – The ModeloDraft to export; must be in APROBADO status.

  • output_path (Path) – Destination path for the fichero-BOE bytes.

  • headers (dict[str, str]) – Registry header fields (NIF, ejercicio, etc.) embedded in the file.

  • schema_provider (RegistrySchemaAccessor | None) – Optional registry schema provider override.

Return type:

DeclaracionExportResult

Returns:

A DeclaracionExportResult with the output path, digest, byte size, and casilla provenance for the exported declaration.

See also

verify_export()

Re-read a local export file and compare parser-covered casillas against the approved draft.

application.modelo._export.export_modelo_revision()

Work-unit-facing export orchestration that supplies an approved draft reconstructed from a calculation revision.

domain.calculations.registry.parse_export_payload()

Registry parser used by the verification path.

export_layout_renderability_reason(modelo, layout)[source]

Return why layout cannot currently produce local declaration bytes.

Return type:

str | None

Parameters:
verify_export(draft, *, file_path, schema_provider=None)[source]

Verify a local export file against an approved ModeloDraft.

The verifier parses the file through the draft’s active registry export layout and compares parser-covered casillas against the draft. MATCH means the covered casillas agree; it does not imply every draft casilla was present on the wire. Draft casillas outside parser coverage are reported in DeclaracionVerifyResult.unchecked_casilla_ids.

Return type:

DeclaracionVerifyResult

Returns:

A DeclaracionVerifyResult with a closed DeclaracionVerifyVerdict, file digest when available, mismatched casillas, unchecked casillas, and provenance.

Parameters:

See also

export_draft()

Write the local fichero-BOE artefact being verified.

domain.calculations.registry.parse_export_payload()

Registry parser used to read the file.

render_layout(layout, *, draft, headers)
Return type:

bytes

Parameters:
boe_representable_casilla_ids(layout, *, headers, schema_provider)[source]

Return the casillas the .boe layout files a slot for, for this disposition.

A casilla is representable when the official record design carries a field for it that this draft’s disposition does not suppress. xml_dictionary layouts derive their casillas from the dictionary entries; fixed_width layouts from every CASILLA field plus the binding-row casilla mappings (row_field_casilla_ids), across records not suppressed for the disposition (e.g. the DID refund page on a non-refund filing).

The completeness gate intersects the calculation-completeness manifest with this set: a manifest casilla absent here is a calculation-closure casilla the official filed record does not carry, so it is out of scope for the .boe parity gate rather than a drift.

Return type:

frozenset[TypeAliasType]

Parameters:
rendered_casilla_ids(layout, *, draft, headers, schema_provider)[source]

Return the representable casillas whose value actually reaches disk.

A representable casilla reaches disk only when the ModeloDraft carries a value for it; a representable casilla absent from draft.values renders as a blank fixed-width slot (or an omitted xml element), which is the structurally-thin file the completeness gate exists to refuse. This is the rendered set the gate compares against the manifest-required-and-representable set.

Return type:

frozenset[TypeAliasType]

Parameters:
assert_export_mirrors_manifest(layout, *, draft, headers, schema_provider, manifest, casilla_metadata)[source]

Panic if the .boe would not mirror the manifest-required structure.

The completeness gate: every casilla that is a calculation RESULT (declares a formula) or is schema-required, and that the calculation-completeness manifest lists AND the official record files (representable for this ModeloDraft’s disposition), MUST carry a value on disk. Such a casilla rendered blank means the calculation did not populate it – a structurally-thin file behind a valid SHA-256 digest, which this gate refuses with a hard FilingExportError naming every missing casilla with its official record number and segmento, so the panic is loud and explicit.

Optional operator-input casillas – retenciones, prior payments, deductions the taxpayer may legitimately not have – are NOT required to carry a value: a blank slot for them is a valid zero, not a thin file (grounded in the AEAT casilla semantics; e.g. Modelo 131 casillas 02/08/09/12/14 are optional inputs), so they are excluded from the required set. A manifest casilla absent from the representable set is a calculation-closure casilla the official record does not file and is likewise out of scope. Callers pass manifest only when the revision declares one; a revision without a manifest is handled by the coverage-advisory path, not here.

The gate applies only to the fixed-width fichero-BOE. In that format every field occupies its byte slot always, so an omitted required casilla renders a blank slot behind a valid digest – the structurally-thin file. An xml_dictionary export instead omits an absent casilla as an absent optional element, which is legitimate (a filer declares only the casillas its situation requires), so completeness is not asserted for that transport.

Beyond casilla presence, the gate asserts two further structural-fidelity dimensions before any bytes are written, so the .boe mirrors the official modelo-revision structure and not merely its casilla set:

  • Record/section order: the records that reach disk, emitted in their declared order, must follow the registry export-layout declaration order, and no two rendered records may share an order (_assert_record_order_fidelity()).

  • Casilla numbering/segmento: every manifest casilla the official record files a slot for must carry the same (number, segmento) the registry CasillaDefinition declares – re-grounded against the projected CasillaRecordMetadata, not the manifest’s own copy (_assert_casilla_metadata_fidelity()).

Each dimension is a hard, enumerated FilingExportError; a structural divergence is a failure, never a warning.

Return type:

None

Parameters: