aeat.application.overview._coverage module

Obligation-coverage reconciliation for the overview surface.

The default overview surfaces (calendar / agenda / backlog) answer “what must this taxpayer file?”. A filing obligation reaches those surfaces only when it has BOTH a registered deadline window (so the deadline engine emits it) AND a positively APPLICABLE seed applicability verdict (so the calendar keeps it). A modelo that lacks either is otherwise dropped without a default-visible trace, so an operator — or the autonomous agent the CLI targets — trusting the surface would under-file.

This module reconciles the full registry_modelo_codes() set against what the calendar positively resolved and classifies every registry modelo into exactly one disposition:

  • surfaced — it was resolved by a registry window and an applicable verdict;

  • confidently excluded — the taxpayer model positively answers “no” for it (NOT_APPLICABLE / ATTRIBUTION_PASS_THROUGH): an answered question, no advisory needed;

  • advised — it is applicable-but-window-less (e.g. Modelo 190) or its applicability is undetermined (INCOMPLETE): an unanswered question the operator MUST investigate;

  • out of scope — it is listed in OUT_OF_SCOPE_OBLIGATIONS with a recorded product-scope reason.

The classification is total by construction, so no registry modelo can be silently absent. The advised set is projected into a default-visible Notice by the CLI, closing the no-silent-under-declaration gap one layer up, at obligation determination.

class CoverageAdviceReason(*values)[source]

Bases: StrEnum

Why an unsurfaced obligation is advised rather than silently dropped.

Variables:

  • APPLICABLE_WINDOW_MISSING – The taxpayer model positively triggers the modelo (verdict APPLICABLE) but the registry carries no deadline window for it, so the engine never placed it on the calendar. This is the former Modelo-190 shape — a genuine data gap.

  • APPLICABILITY_UNDETERMINED – The seed applicability table cannot yet decide the modelo for this profile (verdict INCOMPLETE — no seed rule, or a payer/enrolment fact left undeclared). The operator must investigate whether it applies.

  • REGISTRY_UNMODELED – The modelo is a recognized AEAT obligation (UNMODELED_OBLIGATIONS) that the registry does not model at all, so neither a window nor an applicability rule exists. It surfaces as advised — “AEAT may expect this; the app cannot yet scope it” — rather than being invisible.

APPLICABLE_WINDOW_MISSING
APPLICABILITY_UNDETERMINED
REGISTRY_UNMODELED
class AdvisedObligation(**data)[source]

Bases: BaseModel

One registry modelo the operator must investigate, with its reason.

Parameters:
modelo: str
reason: CoverageAdviceReason
class ObligationCoverageReport(**data)[source]

Bases: BaseModel

Total partition of the registry modelo set by coverage disposition.

Every registry_modelo_codes() code lands in exactly one of the four tuples. advised is the load-bearing field: a non-empty advised means the default surface would otherwise have hidden a filing obligation the operator must investigate.

Variables:

  • surfaced – Modelos positively resolved by registry windows and applicability for the queried schedule horizon.

  • confidently_excluded – Modelos the taxpayer model positively answers “no” for — answered, so no advisory is raised.

  • advised – Modelos the operator must investigate (window-missing or applicability-undetermined), each with its CoverageAdviceReason.

  • out_of_scope – Modelos declared out of scope in OUT_OF_SCOPE_OBLIGATIONS.

Parameters:
surfaced: tuple[str, ...]
confidently_excluded: tuple[str, ...]
advised: tuple[AdvisedObligation, ...]
out_of_scope: tuple[str, ...]
property advised_modelos: tuple[str, ...]

Return just the advised modelo codes, in report order.

property has_advisories: bool

Return whether any obligation must be investigated.

build_obligation_coverage(profile, surfaced_modelos, *, today)[source]

Reconcile surfaced obligations against the full registry modelo set.

Walks every registry_modelo_codes() code and assigns it to exactly one disposition (see ObligationCoverageReport). The classification is total, so a modelo can never be silently absent: one that is neither surfaced, nor confidently excluded, nor explicitly out of scope is advised, and the CLI raises a default-visible advisory for it.

Parameters:

  • profile (TaxpayerProfile) – The operator’s three-axis TaxpayerProfile.

  • surfaced_modelos (Iterable[str]) – The modelo codes positively resolved by a registry deadline window and an applicable verdict for the queried schedule horizon. They need not have an entry inside the UI date range; an annual row outside a two-week agenda is still resolved, not a grounding gap.

  • today (date) – Reference date for applicability evaluation (the Modelo-720 Beckham-window check is date-sensitive).

Return type:

ObligationCoverageReport

Returns:

The ObligationCoverageReport partition.