aeat.application.calculations._ports module

Structural calculation ports for read-only filed declaration data.

These runtime-checkable protocols declare the subset of AEAT filed-declaration records that the calculations application layer reads without importing the Sede adapter. Concrete records such as FiledDeclaracionObservation, FiledDeclaracionArtefact, and ObservedCasillaValue satisfy these ports structurally while remaining adapter-owned evidence records.

See also

application.calculations._iva_compensation_history:

Consumes FiledDeclaracionObservationProtocol for Modelo 303 period states and Modelo 390 annual cross-checks.

application.live:

Captures filed declarations and promotes registry-consumable observations into local encrypted stores.

class FiledDeclaracionArtefactProtocol(*args, **kwargs)

Bases: Protocol

Minimal artefact surface read by calculation evidence consumers.

The concrete FiledDeclaracionArtefact carries more capture metadata, but calculation history only needs the artefact kind and hash witness to choose submitted-file evidence where it is present.

property kind: str

Artefact kind identifier, for example submitted_file.

property sha256: str | None

SHA-256 hex digest of the artefact, when available.

class ObservedCasillaValueProtocol(*args, **kwargs)

Bases: Protocol

Minimal casilla-observation surface read by calculations.

Values arrive as read-only evidence from an adapter-owned ObservedCasillaValue. The application treats casilla_id as a canonical CasillaId string and validates it against the resolved registry snapshot before using the value.

property source_artefact_kind: str

Source artefact kind that produced this observation.

property casilla_id: CasillaId

Canonical CasillaId string observed in the filed artefact.

property value: str

Raw string value for the casilla observation.

class FiledDeclaracionObservationProtocol(*args, **kwargs)

Bases: Protocol

Structural interface for a filed AEAT declaration observation.

The application layer depends on this protocol rather than the concrete FiledDeclaracionObservation model, eliminating the application-to-adapter import edge. The surface is intentionally limited to the fields consumed by iva_compensation_state_from_filed_observation() and iva_compensation_annual_summary_from_filed_observation().

property modelo: str

AEAT modelo identifier (e.g. ‘303’).

property ejercicio: int

Tax year (fiscal year) for this declaration.

property period: Period

Typed Period for the declaration.

property expediente_id: str

AEAT expediente identifier.

property status: str

Filing status string.

property presented_at: datetime

Timestamp when the declaration was presented to AEAT.

property authenticated_identity: str

NIF of the authenticated taxpayer who presented the declaration.

property artefacts: Sequence[FiledDeclaracionArtefactProtocol]

Sequence of artefacts attached to this declaration.

Each element satisfies FiledDeclaracionArtefactProtocol.

property casillas: Sequence[ObservedCasillaValueProtocol]

Sequence of ObservedCasillaValueProtocol values extracted from the declaration.