aeat.application.evidence._models module

Pydantic models for operator-facing evidence bundles.

An evidence bundle is a content-addressed manifest that groups related persisted records (calculation revisions, filing records, and their attached objects) under a single verifiable identity. The bundle’s bundle_id is a SHA-256 hash of the canonical manifest inputs so it is stable across re-imports of the same data and globally unique per bucket + work-unit + manifest-version triple.

Key types:

Bundle manifests reference work-unit, calculation-revision, and filing-record payloads without replacing those catalogues as the source of truth. Verification replays the manifest against supplied object bytes and reports reachability and digest results without contacting AEAT.

exception EvidenceBundleNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when an evidence-bundle lookup misses by id.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception EvidenceBundleVerificationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when bundle verification fails and the caller refuses --force-incomplete.

The verification service raises this when one or more VerificationCheck items fail and the operator has not passed an override flag that permits incomplete bundles.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class BundleVerificationState(*values)[source]

Bases: StrEnum

Closed lifecycle states for a EvidenceBundle’s verification status.

PENDING is the initial state when a bundle is first written. VERIFIED means all VerificationCheck items passed. INCOMPLETE means reachability or digest checks found missing records but the operator accepted the partial bundle. FAILED means at least one blocking integrity check failed.

PENDING
VERIFIED
INCOMPLETE
FAILED
class VerificationCheck(*values)[source]

Bases: StrEnum

Named integrity checks a bundle’s offline verification pass runs.

Each member identifies one distinct check the verifier executes against the bundle manifest and the backing object store:

  • MANIFEST_DIGEST — recompute bundle_id and compare.

  • RECORD_DIGESTS — re-hash each referenced object payload.

  • BUCKET_BINDING — confirm the bundle’s bucket_id matches the repository it was loaded from.

  • WORK_UNIT_BINDING — confirm the work_unit_id exists.

  • OBJECT_REACHABILITY — confirm every referenced object is present in the bucket’s object store.

MANIFEST_DIGEST
RECORD_DIGESTS
BUCKET_BINDING
WORK_UNIT_BINDING
OBJECT_REACHABILITY
class EvidenceBundleCheckResult(**data)[source]

Bases: BaseModel

One VerificationCheck outcome from a bundle verification pass.

passed is True when the check succeeded. detail carries a human-readable explanation when the check failed or when extra diagnostic context is available.

Parameters:
check: VerificationCheck
passed: bool
detail: str
class EvidenceRecordRef(**data)[source]

Bases: BaseModel

One referenced record entry inside an EvidenceBundle manifest.

object_type names the BucketEventObjectType of the record; object_id is its stable store key; content_sha256 is the SHA-256 hex digest of the record’s raw payload bytes; payload_size_bytes is the byte count used for completeness-ratio calculation.

Parameters:
object_type: BucketEventObjectType
object_id: str
content_sha256: str
payload_size_bytes: int
class EvidenceBundle(**data)[source]

Bases: BaseModel

One persisted evidence bundle.

The manifest is content-addressed by bundle_id (SHA-256 of the canonical manifest payload). All record references carry their own content digest so bundle verification is offline-pure: given a bucket-scoped object store, a verifier can recompute digests and confirm reachability without contacting AEAT or any remote service.

Parameters:

  • bundle_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)])

  • manifest_version (int)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • work_unit_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)] | None)

  • filing_record_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)] | None)

  • records (tuple[EvidenceRecordRef, ...])

  • verification_state (BundleVerificationState)

  • completeness_ratio (float)

  • created_at (datetime)

  • notes (str)

bundle_id: BundleId
manifest_version: int
bucket_id: BucketId
work_unit_id: WorkUnitId
calculation_revision_id: CalculationRevisionId | None
filing_record_id: FilingRecordId | None
records: tuple[EvidenceRecordRef, ...]
verification_state: BundleVerificationState
completeness_ratio: float
created_at: datetime
notes: str
derive_bundle_id(*, bucket_id, work_unit_id, manifest_version, records, calculation_revision_id=None, filing_record_id=None)[source]

Compute the content-addressed bundle_id for canonical inputs.

The digest covers manifest version, bucket id, work-unit id, optional calculation revision id, optional filing record id, and the ordered EvidenceRecordRef object type/id/content-digest triples.

Return type:

str

Parameters:
utcnow()[source]

Return the current UTC timestamp via core.time.now().

Return type:

datetime