aeat.application.calculations._cross_period_clean_state module

Clean-state proof for filing-grade cross-period modelo dependencies.

evaluate_cross_period_clean_state() derives dependency requirements from a RegistrySnapshot, then joins filed ModeloRecord rows, calculation revisions, verification reports, and justificante evidence into a CrossPeriodCleanStateVerdict.

The same verdict feeds modelo verification, filing, and export gates. See also CrossPeriodDependencyEvidence for per-dependency blocker/advisory rows and ValidatedRegistryAuthority for the authority surface that produces the snapshots evaluated here.

cross_period_dependency_requirements(snapshot)[source]

Return the dependency records for snapshot.

Derives CrossPeriodDependencyRequirement records from RegistrySnapshot through previous_filing_observation_requirements() and relation_source_requirements().

Return type:

tuple[CrossPeriodDependencyRequirement, ...]

Parameters:

snapshot (RegistrySnapshot)

partition_cross_period_requirements_by_activity_start(requirements, *, activity_start_date)[source]

Split registry-derived requirements into in-scope and pre-activity-suppressed.

ADR 2026-06-13-first-filer-attestation-adr: a dependency anchor whose period falls strictly before activity_start_date is no-prior-obligation (absent-by-design) and is scoped out of the evaluated graph. The scoping is an application-layer filter over the registry-derived requirements - the registry stays pure and the declared date is a grounded input (the same field the deadline engine consumes), not a per-call ad hoc shrink (2026-06-05-cross-period-calculation-guards-adr).

The suppression is uniform across BOTH previous_filing bindings and relation_source_requirements origins (the requirement carries its origin field; this predicate is origin-agnostic), so a first filer is never unblocked on one origin and trapped on the other.

When activity_start_date is None every requirement stays in scope; the caller decides whether a missing declared date should fail closed.

Return type:

_RequirementPartition

Parameters:
cross_period_dependency_inventory(authority, *, filing_year, modelos=None)[source]

Return snapshots with cross-period dependencies.

The CrossPeriodDependencyInventory is a backend coverage surface. It lets callers prove which modelos and periods are in scope for the clean-state guard before they wire model-specific workflow tests or operator diagnostics.

The ValidatedRegistryAuthority supplies candidate modelos and resolves each target RegistrySnapshot evaluated for dependency coverage.

Return type:

CrossPeriodDependencyInventory

Parameters:
evaluate_cross_period_clean_state(snapshot, *, bucket_id, observation_repository, filing_repository, calculation_repository, verification_repository, justificante_repository=None, expected_member_sets=(), taxpayer_tax_id=None, activity_start_date=None, modelo_202_modality=None, taxpayer_files_economic_activity=None, not_applicable_source_modelos=None, zero_value_previous_filing_binding_ids=None, m111_no_retenciones_periods=None)[source]

Evaluate cross-period dependencies and return a clean-state verdict.

Returns a CrossPeriodCleanStateVerdict.

The supplied RegistrySnapshot is the authority for target revision, filing period, and dependency requirements.

activity_start_date is the operator-declared activity-start date carried on the profile (the same field the deadline engine consumes for pre-start suppression). When supplied, a dependency whose period falls strictly before it is scoped out as no-prior-obligation (ADR 2026-06-13-first-filer-attestation-adr): it produces a clean, facet-stamped evidence row instead of an evaluated blocker, and is NOT loaded from storage. When None every dependency is evaluated as before - the caller decides whether a missing declared date should fail closed.

modelo_202_modality is the derived Modelo 202 pago-fraccionado modality (derive_modelo_202_modality()). When it is ART_40_2_OPTIONAL (modalidad cuota) AND the recorded activity_start_date places the taxpayer’s first IS year at or after the target filing year, the Modelo 202 cross-period dependency is scoped out as a first-year no-fractional-payment obligation (ADR 2026-06-19-m202-first-period-attestation-adr): a first-year IS filer in modalidad cuota has no prior IS return to provide the art. 40.2 cuota basis, so no pago fraccionado is owed. It is fail-closed everywhere else: under ART_40_3_MANDATORY / INCOMPLETE / None modality, when no activity-start date is recorded, or when the year is not the first IS year, the Modelo 202 dependency stays in scope and keeps blocking. The default None preserves the prior behaviour (no Modelo 202 suppression).

not_applicable_source_modelos carries source modelos that the caller has positively resolved as not applicable for the taxpayer. It is only applied to dependency classifications already marked conditional on economic activity, so the payee/payer classification remains the primary retenciones boundary while the mutually-exclusive M130/M131 regime split can still be enforced without blocking on the modelo the taxpayer does not file. None means the caller could not decide, so no suppression occurs.

zero_value_previous_filing_binding_ids carries whitelisted previous-filing binding ids whose target revision value is explicitly zero. Those requirements are retained as clean advisory rows rather than demanding evidence of a prior filing for a carry the taxpayer is not claiming. Nonzero carries and every binding not named here stay fully in scope.

m111_no_retenciones_periods carries explicit profile attestations that no Modelo 111 filing obligation existed for a source period because no rentas subject to withholding/ingreso a cuenta were paid. It scopes out only those exact M111 periods; nonzero and unknown periods remain fully evaluated.

Return type:

CrossPeriodCleanStateVerdict

Parameters:
filing_external_evidence_blockers(filing, observation_source_kind, justificante_repository, taxpayer_tax_id, observation_source_metadata=None)
Return type:

list[CrossPeriodCleanStateBlocker]

Parameters: