cadrumo.application.calculations.cross_period_models module

Typed records for cross-period clean-state evaluation.

class CrossPeriodDependencyOrigin(*values)

Bases: StrEnum

Registry source family that created a cross-period dependency.

PREVIOUS_FILING_BINDING

REGISTRY_RELATION

class CrossPeriodCleanStateBlocker(*values)

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

UNRESOLVED_TAXPAYER_IDENTITY

No taxpayer identity was resolvable, so the justificante could not be identity-checked.

Distinct from MISMATCHED_EXTERNAL_EVIDENCE_RECORD, which asserts the stored receipt belongs to someone else. Both once reported the same code, so an operator whose profile simply carried no NIF was told their filed evidence was mismatched – pointing them at the receipt rather than at the profile field they had not filled in. The check is still fail-closed: an unidentifiable receipt cannot satisfy the clean-state gate. Only the reason given to the operator changes, and it is the reason that tells them what to fix.

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.

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.

OPERATOR_ACTION_BY_CROSS_PERIOD_CLEAN_STATE_BLOCKER: Mapping[CrossPeriodCleanStateBlocker, OperatorActionAxis]

Total operator-action projection retaining each native clean-state blocker.

class NoPriorObligationProvenanceKind(*values)

Bases: StrEnum

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

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 an official ObservationSourceKind (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. Censal facts are operator-supplied through config profile edit (the live Modelo 036 censo read was retired: AEAT exposes no read-only “Mis Datos Censales” projection), so this is the sole provenance kind for a scoped-out no-prior-obligation dependency. Carries the advisory.

class NoPriorObligationProvenance(**data)

Bases: BaseModel

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

Records the activity-start date that scoped a pre-activity dependency out of the requirement graph and the provenance kind of that date. The date is operator-declared — censal facts are operator-supplied through config profile edit since the live Modelo 036 censo read was retired — so OPERATOR_DECLARED is the sole provenance kind. The suppression is an explicit, auditable outcome (no-silent-under-declaration), never a silent omission.

Parameters:

data (Any)

facet_kind: NoPriorObligationProvenanceKind

activity_start_date: date

provenance_kind: NoPriorObligationProvenanceKind

property is_operator_declared: bool

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

ObservationPayload

alias of _ObservationPayload

period_strictly_before_activity_start(period, activity_start_date)

Report whether period closes before economic activity began.

Return type:

bool

Parameters:

• period (Period)

• activity_start_date (date)

class CrossPeriodDependencyRequirement(**data)

Bases: BaseModel

One upstream filed declaration required by a target registry snapshot.

Parameters:

data (Any)

source_modelo: str

filing_year: FilingYear

period: Period

source_casilla_ids: tuple[CasillaId, ...]

required_source_casilla_ids: tuple[CasillaId, ...] | None

source_presence_groups: tuple[tuple[CasillaId, ...], ...]

origin: CrossPeriodDependencyOrigin

origin_ids: tuple[str, ...]

legal_refs: tuple[LegalRefId, ...]

source_refs: tuple[SourceRefId, ...]

requires_member_fan_in: bool

property enforced_source_casilla_ids: tuple[CasillaId, ...]

Return mandatory source casillas, defaulting to every candidate.

property key: tuple[str, int, str, CrossPeriodDependencyOrigin, tuple[str, ...]]

Return the identity tuple that distinguishes this dependency.

class CrossPeriodExpectedMemberSet(**data)

Bases: BaseModel

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

Parameters:

data (Any)

source_modelo: str

filing_year: FilingYear

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)

Bases: BaseModel

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

Parameters:

data (Any)

target_modelo: str

target_revision_id: RevisionId

target_filing_year: FilingYear

target_period: Period

dependencies: tuple[CrossPeriodDependencyRequirement, ...]

property source_modelos: tuple[str, ...]

Return the upstream modelos required by this target snapshot.

class CrossPeriodDependencyInventory(**data)

Bases: BaseModel

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

Parameters:

data (Any)

filing_year: FilingYear

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)

Bases: BaseModel

Observed filing-state evidence for one dependency requirement.

This model IS the clean-state verdict’s evidence: a requirement whose evidence carries no blockers is reported clean, and a filing proceeds on that answer. Declaring the identities and provenance as bare strings therefore admitted evidence that could not exist – an observation source outside the closed provenance taxonomy, filing-record and calculation-revision references that are not the canonical hex-64 identities, an external-evidence kind naming no known evidence – and the enclosing verdict still reported clean=True, because nothing had put a blocker on it. Malformed evidence is not clean evidence; it is evidence that was never observed.

Every identity and provenance field is now the canonical type its producer already holds, so a value the rest of the system could never have minted is refused at construction rather than laundered into a filing decision.

Parameters:

data (Any)

requirement: CrossPeriodDependencyRequirement

observation_source_kind: ObservationSourceKind | None

filing_record_id: FilingRecordId | None

calculation_revision_id: CalculationRevisionId | None

member_filing_record_ids: tuple[FilingRecordId, ...]

member_calculation_revision_ids: tuple[CalculationRevisionId, ...]

calculation_revision_state: CalculationRevisionState | None

verification_status: VerificationCompletenessStatus | None

aeat_accepted: bool | None

external_evidence_kind: ExternalEvidenceKind | 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.

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

Report whether this dependency carries no blockers.

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.

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 (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)

Bases: BaseModel

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

Parameters:

data (Any)

bucket_id: BucketId

target_modelo: str

target_filing_year: FilingYear

target_period: Period

dependencies: tuple[CrossPeriodDependencyEvidence, ...]

property requires_clean_state: bool

Report whether any dependency must reach a clean state.

property clean: bool

Report whether every dependency is clean.

property blockers: tuple[CrossPeriodCleanStateBlocker, ...]

Return the deduplicated blockers across every dependency.