aeat.application.evidence._service module

Build, verify, export, and replay EvidenceBundle manifests.

EvidenceBundleService persists bundles through EvidenceBundleRepository and reports integrity checks as an EvidenceBundleVerificationReport.

The repository is a SecureBoundRepository namespace for encrypted Envelope-wrapped bucket-local manifests, with the namespace, schema version, object-key grammar, and custody disposition declared by adapters.persistence.storage.APPLICATION_EVIDENCE_BUNDLE_NAMESPACE. 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 EvidenceBundleRepository(*, bucket_id=None, objects=None, settings=None)[source]

Bases: SecureBoundRepository[EvidenceBundle]

Encrypted repository for bucket-local EvidenceBundle manifests.

The namespace, sensitivity, schema version, and payload type come from adapters.persistence.storage.APPLICATION_EVIDENCE_BUNDLE_NAMESPACE so evidence bundles use the same secure-object envelope contract as other sensitive bucket-local application state. The SecureBoundRepository base wraps each EvidenceBundle in a Envelope before writing it.

See also

EvidenceBundleService

Service layer that builds, verifies, exports, and replays bundles.

SecureBoundRepository

Generic encrypted-envelope repository base used by this store.

Parameters:
namespace: ClassVar[str]
sensitivity: ClassVar
schema_version: ClassVar[int]
payload_type

alias of EvidenceBundle

extract_identifier(payload)[source]

Return the stable storage key for an EvidenceBundle.

Return type:

str

Parameters:

payload (EvidenceBundle)

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:
bundle_id: BundleId
verification_state: BundleVerificationState
findings: tuple[EvidenceBundleCheckResult, ...]
completeness_ratio: float
class EvidenceBundleService(settings=None, repository_factory=None)[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, export, replay are operator-facing.

Persisted manifests stay inside EvidenceBundleRepository. Exported ZIP archives are separate caller-directed artifacts and are never treated as authoritative storage records.

Parameters:
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 EvidenceBundleRepository.

Return type:

EvidenceBundle

Parameters:
show(*, bucket_id, bundle_id)[source]

Load a bundle by exact or prefix match of bundle_id.

Tries an exact repository.load first; falls back to a prefix scan over all records in the bucket. Raises EvidenceBundleNotFoundError when nothing matches.

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:
replay(*, bucket_id, bundle_id, record_payloads=None)[source]

Evidence-case replay: re-verify the bundle against supplied payloads.

Replay never contacts AEAT and never performs live submission. Behaviorally this is check with a different verb name and intent: check is operator diagnostics, replay is the forensic verb invoked when reproducing a historical filing for audit handoff.

Returns an EvidenceBundleVerificationReport.

Return type:

EvidenceBundleVerificationReport

Parameters: