aeat.application.calculations._cross_period_models module

Typed records for cross-period clean-state evaluation.

class CrossPeriodDependencyOrigin(*values)[source]

Bases: StrEnum

Registry source family that created a cross-period dependency.

PREVIOUS_FILING_BINDING
REGISTRY_RELATION
class CrossPeriodCleanStateBlocker(*values)[source]

Bases: StrEnum

Blocking reason codes for a cross-period clean-state verdict.

MISSING_OBSERVATION
MISSING_OBSERVED_CASILLA
MISSING_CURRENT_FILING_RECORD
DUPLICATE_CURRENT_FILING_RECORD
SUPERSEDED_DEPENDENCY
MISSING_CALCULATION_REVISION
UNFILED_CALCULATION_REVISION
MISSING_COMPLETE_VERIFICATION_REPORT
LOCAL_FILING_MISSING_EXTERNAL_EVIDENCE
MISSING_AEAT_ACCEPTANCE
MISSING_EXTERNAL_EVIDENCE
MISSING_EXTERNAL_EVIDENCE_RECORD
MISMATCHED_EXTERNAL_EVIDENCE_RECORD
MISSING_JUSTIFICANTE_VERIFICATION
OBSERVATION_REVISION_VALUE_DIVERGENCE
OPERATOR_MANUAL_SOURCE
INCOMPLETE_GROUP_MEMBER_COVERAGE
MISSING_EXPECTED_GROUP_MEMBER_ROSTER
UNEXPECTED_GROUP_MEMBER_SOURCE
REGISTRY_REVISION_DIVERGENCE

Stamped revision id does not re-confirm against the law-determined revision for the source.

ADR 2026-06-10-period-revision-resolution-adr, Ruling 3 / R2: a prior observation captured under a revision that is no longer the law-determined revision for its source context, or whose source context cannot be resolved for re-confirmation, must not silently propagate its norms. The carry is refused until the operator re-files and re-stamps under the current revision.

class NoPriorObligationProvenanceKind(*values)[source]

Bases: StrEnum

Provenance family for a no-prior-obligation pre-activity suppression.

ADR 2026-06-13-first-filer-attestation-adr: a cross-period dependency anchor whose period falls strictly before the taxpayer’s recorded activity-start date is scoped out of the requirement graph. The scoping is stamped with the provenance of the activity-start date that justified it.

The NO_PRIOR_OBLIGATION_PRE_ACTIVITY value is the facet-kind discriminator carried on the evidence row; it names a suppression, not an evidence source, and is therefore categorically never a member of _OFFICIAL_SOURCE_KINDS (which families a filing’s AEAT evidence). The regression in test_cross_period_clean_state_enforcement.py pins that exclusion.

NO_PRIOR_OBLIGATION_PRE_ACTIVITY

this requirement was suppressed because its period is pre-activity (no prior obligation could have existed).

Type:

The facet-kind discriminator

NO_FRACTIONAL_PAYMENT_OBLIGATION_FIRST_YEAR

this Modelo 202 pago-fraccionado requirement was suppressed because the taxpayer is a first-year Impuesto sobre Sociedades filer under modalidad cuota (LIS art. 40.2). The pago fraccionado in modalidad cuota is computed as a percentage of the cuota íntegra of the LAST IS return whose filing deadline has elapsed (LIS art. 40.2); a company whose first IS year is the target year has no such prior IS return, so the art. 40.2 modality produces no pago-fraccionado obligation and the cross-period dependency demanding evidence of a prior Modelo 200/202 that never existed is scoped out. This applies ONLY to art. 40.2 (cuota) — under art. 40.3 (base imponible, INCN > 6.000.000 €) the pago fraccionado is computed on the current year’s running base and IS owed in the first year, so that modality is never suppressed.

Type:

The facet-kind discriminator

OPERATOR_DECLARED

The activity-start date is the operator-declared activity_start_date field (not corroborated by an AEAT censo snapshot). Carries the advisory.

CENSO_CORROBORATED

The activity-start date was corroborated against an AEAT censo snapshot. Deferred per the accepted ADR until the live censo read is functional; declared above for the upgrade path so the facet vocabulary is stable.

class NoPriorObligationProvenance(**data)[source]

Bases: BaseModel

Typed marker that a dependency was scoped out as no-prior-obligation.

ADR 2026-06-13-first-filer-attestation-adr (operator-declared now, censo-corroborated when the live censo surface is fixed): records the activity-start date that scoped a pre-activity dependency out of the requirement graph, the provenance kind of that date, and - when present - the AEAT censo snapshot id that corroborated it. The suppression is an explicit, auditable outcome (no-silent-under-declaration), never a silent omission.

Parameters:
facet_kind: NoPriorObligationProvenanceKind
activity_start_date: date
provenance_kind: NoPriorObligationProvenanceKind
censo_snapshot_id: str | None
property is_operator_declared: bool

True when the activity-start date is operator-declared (carries the advisory).

class CrossPeriodDependencyRequirement(**data)[source]

Bases: BaseModel

One upstream filed declaration required by a target registry snapshot.

Parameters:
source_modelo: str
filing_year: int
period: Period
source_casilla_ids: tuple[CasillaId, ...]
origin: CrossPeriodDependencyOrigin
origin_ids: tuple[str, ...]
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
requires_member_fan_in: bool
property key: tuple[str, int, str, CrossPeriodDependencyOrigin, tuple[str, ...]]
class CrossPeriodExpectedMemberSet(**data)[source]

Bases: BaseModel

Expected grupo-de-entidades members for one member fan-in dependency.

Parameters:
source_modelo: str
filing_year: int
period: Period
member_nifs: tuple[str, ...]
property requirement_key: tuple[str, int, str]

Return the dependency key this expected member roster proves.

class CrossPeriodDependencyInventoryItem(**data)[source]

Bases: BaseModel

Registry-derived cross-period dependency coverage for one target snapshot.

Parameters:
target_modelo: str
target_revision_id: str
target_filing_year: int
target_period: Period
dependencies: tuple[CrossPeriodDependencyRequirement, ...]
property source_modelos: tuple[str, ...]

Return the upstream modelos required by this target snapshot.

class CrossPeriodDependencyInventory(**data)[source]

Bases: BaseModel

Registry-derived inventory of all cross-period target snapshots for a filing year.

Parameters:
filing_year: int
items: tuple[CrossPeriodDependencyInventoryItem, ...]
property target_modelos: tuple[str, ...]

Return target modelos that declare filing-history dependencies.

property source_modelos: tuple[str, ...]

Return upstream modelos required by the inventory.

class CrossPeriodDependencyEvidence(**data)[source]

Bases: BaseModel

Observed filing-state evidence for one dependency requirement.

Parameters:
requirement: CrossPeriodDependencyRequirement
observation_source_kind: str | None
filing_record_id: str | None
calculation_revision_id: str | None
member_filing_record_ids: tuple[str, ...]
member_calculation_revision_ids: tuple[str, ...]
calculation_revision_state: CalculationRevisionState | None
verification_status: VerificationCompletenessStatus | None
aeat_accepted: bool | None
external_evidence_kind: str | None
observed_member_nifs: tuple[str, ...]
expected_member_nifs: tuple[str, ...]
missing_member_nifs: tuple[str, ...]
unexpected_member_nifs: tuple[str, ...]
blockers: tuple[CrossPeriodCleanStateBlocker, ...]
no_prior_obligation: NoPriorObligationProvenance | None

Typed marker that this dependency was scoped out as no-prior-obligation.

ADR 2026-06-13-first-filer-attestation-adr: when the requirement’s period falls strictly before the taxpayer’s recorded activity-start date, the dependency is suppressed (no prior obligation could have legally existed) and this facet records the activity-start date and provenance that justified it. A suppressed requirement carries no blockers and is clean, but the suppression is explicit and auditable here rather than a silent omission (no-silent-under-declaration). None for an in-scope dependency.

non_official_local_chain_advisory: bool

a same-year app_filing chain admitted, lacking only official AEAT evidence.

Type:

Non-blocking advisory

modelo_not_applicable_advisory: bool

a dependency on a modelo the taxpayer suffers but does not file (not-applicable).

Type:

Non-blocking advisory

zero_value_previous_filing_advisory: bool

an explicit zero previous-filing carry needed no source-filing proof.

This is deliberately narrower than no-prior-obligation suppression: it applies only when the verification caller has proven that the target revision carries an operator-supplied zero for a whitelisted previous-filing binding whose positive value would be a taxpayer benefit. A nonzero carry still requires the prior filing evidence.

Type:

Non-blocking advisory

m111_no_retenciones_no_obligation_advisory: bool

an M111 source period was explicitly attested as no-obligation.

Modelo 111 instructions distinguish a negative return (subject payments made but no effective withholding) from a period with no subject payments at all. The latter must not be filed as an all-blank M111, so a cross-period dependency on that period can be scoped out only when the profile carries the explicit no-retenciones period token.

Type:

Non-blocking advisory

property clean: bool
property suppressed_pre_activity: bool

True when this dependency was scoped out as no-prior-obligation pre-activity.

Scoped to the NO_PRIOR_OBLIGATION_PRE_ACTIVITY facet specifically: a dependency suppressed under the first-year Modelo 202 modalidad-cuota facet is NOT a pre-activity suppression and must not read as one (the two suppressions raise different advisories — see suppressed_first_year_fractional).

property suppressed_first_year_fractional: bool

True when this dependency was scoped out as a first-year Modelo 202 modalidad-cuota.

ADR 2026-06-19-m202-first-period-attestation-adr: a first-year IS filer under modalidad cuota (LIS art. 40.2) has no Modelo 202 pago-fraccionado obligation, so the cross-period dependency demanding evidence of a prior Modelo 200/202 that never existed is scoped out under the NO_FRACTIONAL_PAYMENT_OBLIGATION_FIRST_YEAR facet.

property operator_declared_suppression_advisory: bool

True when the PRE-ACTIVITY suppression rests on an operator-declared (uncorroborated) date.

The verification caller raises a NON-BLOCKING advisory for this case per the accepted ADR (operator-declared now, censo-corroborated when the live censo surface is fixed). Scoped to the pre-activity facet only: the first-year Modelo 202 modalidad-cuota suppression carries its own distinct advisory (suppressed_first_year_fractional) and must not cross-fire this one.

class CrossPeriodCleanStateVerdict(**data)[source]

Bases: BaseModel

Clean-state result for every cross-period dependency in a target snapshot.

Parameters:
bucket_id: str
target_modelo: str
target_filing_year: int
target_period: Period
dependencies: tuple[CrossPeriodDependencyEvidence, ...]
property requires_clean_state: bool
property clean: bool
property blockers: tuple[CrossPeriodCleanStateBlocker, ...]
property has_non_official_local_chain_advisory: bool

True when any dependency was admitted as a same-year non-official local chain.

property has_modelo_not_applicable_advisory: bool

True when any dependency was scoped out as not-applicable (taxpayer suffers, does not file).

property has_zero_value_previous_filing_advisory: bool

True when an explicit zero previous-filing carry was scoped out.

property has_m111_no_retenciones_no_obligation_advisory: bool

True when any M111 source period was scoped out as no-retenciones/no-obligation.

property suppressed_pre_activity_dependencies: tuple[CrossPeriodDependencyEvidence, ...]

Return dependencies scoped out as no-prior-obligation pre-activity.

Returns:

The CrossPeriodDependencyEvidence entries suppressed as pre-activity.

property has_operator_declared_suppression_advisory: bool

True when any pre-activity suppression rests on an operator-declared (uncorroborated) date.

property suppressed_first_year_fractional_dependencies: tuple[CrossPeriodDependencyEvidence, ...]

Return dependencies scoped out as first-year Modelo 202 modalidad-cuota.

ADR 2026-06-19-m202-first-period-attestation-adr.

Returns:

The CrossPeriodDependencyEvidence entries suppressed as a first-year no-fractional-payment obligation (LIS art. 40.2).

property has_first_year_fractional_suppression_advisory: bool

True when any dependency was scoped out as a first-year Modelo 202 modalidad-cuota.

The verification caller raises a NON-BLOCKING advisory for this case (ADR 2026-06-19-m202-first-period-attestation-adr): a first-year IS filer under modalidad cuota (LIS art. 40.2) has no Modelo 202 obligation, but if the entity elected modalidad base (art. 40.3) it IS obligated; the operator bears legal responsibility for the modality, so the suppression is surfaced non-silently.