cadrumo.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:

• EvidenceBundle — the persisted manifest record.

• EvidenceRecordRef — one record reference inside the manifest.

• BundleVerificationState — closed lifecycle states for offline bundle verification.

• derive_bundle_id() — content-addressed id derivation.

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, translated_message=None)

Bases: CadrumoError

Raised when an evidence-bundle lookup misses by id.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

exception EvidenceBundleVerificationError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

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)

• translated_message (str | None)

Return type:

None

code

class BundleVerificationState(*values)

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)

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)

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:

data (Any)

check: VerificationCheck

passed: bool

detail: _CheckDetail

class EvidenceRecordRef(**data)

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 canonical ContentDigest of the record’s raw payload bytes, so a non-hex digest is refused on construction rather than at the later verification pass that recomputes it; payload_size_bytes is the byte count used for completeness-ratio calculation.

Parameters:

data (Any)

object_type: BucketEventObjectType

object_id: str

content_sha256: ContentDigest

payload_size_bytes: NonNegativeInt

class EvidenceBundle(**data)

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:

data (Any)

bundle_id: Hex64Str

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: UnitFraction

created_at: datetime

notes: EvidenceBundleNotes

derive_bundle_id(*, bucket_id, work_unit_id, manifest_version, records, calculation_revision_id=None, filing_record_id=None)

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:

• bucket_id (str)

• work_unit_id (str)

• manifest_version (int)

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

• calculation_revision_id (CalculationRevisionId | None)

• filing_record_id (str | None)