cadrumo.application.evidence.service module

Build, verify, and export EvidenceBundle manifests.

EvidenceBundleService persists bundles through the required EvidenceBundleRepositoryPort capability and reports integrity checks as an EvidenceBundleVerificationReport. The encrypted storage binding and work-unit catalogue lookup are supplied by the outer composition root through EvidenceBundlePorts. EvidenceBundleService.export() is the narrow operator-directed plaintext exception: it verifies first, writes record bytes to the requested archive path before manifest.json, and does not mutate the secure catalogue.

See also

EvidenceBundle, EvidenceRecordRef, BundleVerificationState, and EvidenceBundleCheckResult.

class EvidenceBundleVerificationReport(**data)[source]

Bases: BaseModel

Outcome of a verification pass over an EvidenceBundle.

findings carries per-check EvidenceBundleCheckResult values, verification_state is the summarized BundleVerificationState, and completeness_ratio reports how much of the manifest’s referenced object payload was reachable.

Parameters:

data (Any)

bundle_id: Hex64Str
verification_state: BundleVerificationState
findings: tuple[EvidenceBundleCheckResult, ...]
completeness_ratio: UnitFraction
class EvidenceBundleService(*, ports)[source]

Bases: object

Application service for the audit verb tree.

Each method maps to one of the verbs in aeat app modelo audit: build is the constructor side of add-equivalent (audit bundles are produced by the file/verify path, not the operator). show, check, and export are operator-facing.

Persisted manifests stay behind the required evidence-bundle repository capability. Exported ZIP archives are separate caller-directed artifacts and are never treated as authoritative storage records.

Parameters:

ports (EvidenceBundlePorts)

build(*, bucket_id, work_unit_id, record_payloads, calculation_revision_id=None, filing_record_id=None, notes='')[source]

Build a new bundle from a mapping of (object_type, object_id) -> raw bytes.

The returned EvidenceBundle has all record refs and provenance metadata populated and has already been saved through the required repository capability.

Return type:

EvidenceBundle

Parameters:

  • bucket_id (str)

  • work_unit_id (str)

  • record_payloads (Mapping[tuple[str, str], bytes])

  • calculation_revision_id (CalculationRevisionId | None)

  • filing_record_id (str | None)

  • notes (str)

show(*, bucket_id, bundle_id)[source]

Load a bundle by exact or unambiguous prefix match of bundle_id.

Tries an exact repository.load first; falls back to a prefix scan over all records in the bucket. Every candidate — exact or prefix — is bound to bucket_id: a manifest whose own bucket_id disagrees with the requested bucket is never returned (it is a foreign or corrupt record, not a match), and a prefix matching more than one bundle in this bucket is refused rather than silently resolved to the first one found.

Raises:

EvidenceBundleNotFoundError – Nothing in bucket_id matches bundle_id, or the prefix matches more than one bundle.

Returns:

The retrieved evidence bundle.

Return type:

EvidenceBundle

Parameters:

  • bucket_id (str)

  • bundle_id (str)

check(*, bucket_id, bundle_id, record_payloads=None)[source]

Re-verify a bundle and return an EvidenceBundleVerificationReport.

The caller supplies the current bucket-scoped object payloads. Each record reference is recomputed and compared to the manifest’s registered digest. The report enumerates which checks passed and the overall verification state. Missing records degrade completeness; mismatched digests fail verification.

When record_payloads is None (the CLI default until the per-object-type loader registry lands), every record reports as unreachable and the bundle is classified as INCOMPLETE — the operator-honest baseline. Callers that already hold payloads in memory (test fixtures, end-to-end driver code) pass them explicitly.

Return type:

EvidenceBundleVerificationReport

Parameters:
export(*, bucket_id, bundle_id, output_path, record_payloads=None, force_incomplete=False)[source]

Write a ZIP with each record file then manifest.json last.

Runs verification first. On failed verification, refuses with EvidenceBundleVerificationError unless force_incomplete is True. Incomplete bundles require force_incomplete=True; failed-verification bundles always refuse. The archive is an operator-directed plaintext export written to output_path; it does not create or update encrypted bucket catalogue records.

Return type:

Path

Parameters: