aeat.domain.modelos._verification_report module¶

Structured verification report produced by aeat app modelo verify.

A VerificationReport is the decision artifact the verify command persists for every run. It captures whether the target calculation CalculationRevision meets the verificado_completo contract, which blocking findings prevent that transition, which inputs are missing, which CasillaId identifiers are unresolved, which waivers were accepted, and what the operator should do next.

The report is bucket-scoped and content-addressed by the verification outcome (parent calculation revision, completeness status, findings, and actor); the run timestamp is a non-identity last-seen body field. Failed verification attempts produce a persisted report (so the audit trail explains why a transition was refused) without mutating the target revision, and an identical-outcome retry collapses onto the same report rather than accumulating.

ModeloActorLabel¶

Validated string identifying the operator who triggered a verification run.

Strips surrounding whitespace; must be 1–64 characters after stripping. Used as verified_by on VerificationReport to record the actor label fed into the content-addressed id derivation.

alias of Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)]

class VerificationCompletenessStatus(*values)[source]¶

Bases: StrEnum

Top-level verdict from one verification run.

COMPLETE — every required input resolved, zero blocking findings. The revision transitions to VERIFICADO_COMPLETO.
INCOMPLETE — required inputs missing or unresolved casillas remain. Soft refusal: operator can act on the missing-inputs list.
BLOCKED — blocking validation findings exist (e.g. reconciliation total mismatch over tolerance, schema violation). Hard refusal: operator must fix the finding before the revision can be verified.

COMPLETE¶

INCOMPLETE¶

BLOCKED¶

class ModeloVerificationFindingKind(*values)[source]¶

Bases: StrEnum

Closed catalogue of verification-finding kinds.

Maps to the readiness vocabulary mandated by the verify ADR: bucket / ledger source / profile fact / prior filed revision / live observation / casilla / waiver / blocking finding.

MISSING_REQUIRED_CASILLA¶

RECONCILIATION_MISMATCH¶

UNRESOLVED_BINDING¶

CROSS_PERIOD_DEPENDENCY_UNCLEAN¶

INVALID_WAIVER¶

BLOCKING_RULE¶

ADVISORY¶

class ModeloVerificationFindingSeverity(*values)[source]¶

Bases: StrEnum

Severity of one verification finding.

BLOCKING¶

WARNING¶

class ModeloVerificationFinding(**data)[source]¶

Bases: BaseModel

One verification finding.

Findings of BLOCKING severity force BLOCKED completeness status. WARNING severity findings surface in the report but do not block COMPLETE status on their own.

A finding may point at the affected CasillaId, the registry VerificationExpectationId that raised it, and the LegalRefId / SourceRefId provenance that grounds the operator-facing message.

Parameters:

kind (ModeloVerificationFindingKind)
severity (ModeloVerificationFindingSeverity)
casilla_id (CasillaId | None)
expectation_id (VerificationExpectationId | None)
message (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])
next_action (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)
legal_refs (tuple[LegalRefId, ...])
source_refs (tuple[SourceRefId, ...])

kind: ModeloVerificationFindingKind¶

severity: ModeloVerificationFindingSeverity¶

casilla_id: CasillaId | None¶

expectation_id: VerificationExpectationId | None¶

message: _FindingMessage¶

next_action: _FindingMessage | None¶

legal_refs: tuple[LegalRefId, ...]¶

source_refs: tuple[SourceRefId, ...]¶

derive_verification_report_id(*, calculation_revision_id, completeness_status, findings, verified_by)[source]¶

Deterministic 64-char SHA-256 id for a verification report.

Content-addressed by the verification outcome - the parent CalculationRevision id, the completeness_status, the ordered findings tuple, and the verified_by actor. run_at is deliberately excluded from the identity so two retries of an identical-outcome verify collapse to one report on upsert (the id is clock-free); a re-verify whose findings change produces a new distinct report, the audit-meaningful granularity.

Return type:

str

Parameters:

calculation_revision_id (str)
completeness_status (VerificationCompletenessStatus)
findings (tuple[ModeloVerificationFinding, ...])
verified_by (str)

class VerificationReport(**data)[source]¶

Bases: BaseModel

Decision record of one verification run against a CalculationRevision.

The id is content-addressed by the verification outcome (calculation_revision_id, completeness_status, findings, and verified_by) via derive_verification_report_id(); run_at is a non-identity last-seen timestamp. A model_validator enforces the derivation on construction so no VerificationReport can carry an inconsistent id.

granted_verificado_completo is True if and only if completeness_status is COMPLETE and no blocking findings exist. The model validator enforces this invariant bidirectionally.

Parameters:

verification_report_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])
calculation_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])
completeness_status (VerificationCompletenessStatus)
findings (tuple[ModeloVerificationFinding, ...])
resolved_casilla_ids (tuple[CasillaId, ...])
missing_required_casilla_ids (tuple[CasillaId, ...])
run_at (datetime)
verified_by (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)])
granted_verificado_completo (bool)

verification_report_id: VerificationReportId¶

calculation_revision_id: _CalculationRevisionId¶

completeness_status: VerificationCompletenessStatus¶

findings: tuple[ModeloVerificationFinding, ...]¶

resolved_casilla_ids: tuple[CasillaId, ...]¶

missing_required_casilla_ids: tuple[CasillaId, ...]¶

run_at: datetime¶

verified_by: ModeloActorLabel¶

granted_verificado_completo: bool¶

class VerificationReportCatalogue(**data)[source]¶

Bases: BaseModel

Immutable catalogue of every verification report in a bucket’s storage.

Keyed by verification_report_id; the model validator enforces that every key equals the id of the VerificationReport it maps to. Iteration yields VerificationReport values (not key–value pairs), which diverges from the standard Mapping contract — the override is annotated with a suppression comment on __iter__.

Parameters:: reports (Mapping[str, VerificationReport])

reports: Mapping[str, VerificationReport]¶

get(verification_report_id)[source]¶

Return the VerificationReport for verification_report_id, or None.

Return type:: VerificationReport | None
Parameters:: verification_report_id (str)

for_calculation_revision(calculation_revision_id)[source]¶

Return every VerificationReport against one calculation revision, ordered by run_at.

Return type:: tuple[VerificationReport, ...]
Parameters:: calculation_revision_id (str)

values()[source]¶: Return a view of all VerificationReport values in the catalogue.