aeat.adapters.persistence.storage.bucket._sealed_archive_errors module

Error classes for the sealed bucket-export archive read / write path.

The classes descend from the existing domain domain.buckets.BucketExportError / BucketImportError so the CLI boundary’s command_error_boundary routes them through the same surface as the other bucket-maintenance verbs. Authority: 2026-06-03-bucket-sealed-archive-adr.

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

Bases: BucketImportError

Raised when the sealed archive’s tar layout does not match the ADR contract.

The expected layout is exactly two or three named members in the order header.json, payload.envelope, and optionally recovery.wrap. Extra members, out-of-order members, and unknown member names all raise this error before any decryption attempt so a tampered or wrong-version archive fast-fails at the layout boundary.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: BucketImportError

Raised when header.json fails strict-validation as ExportArchiveHeader.

Covers both schema-shape mismatches (missing or extra fields, wrong types, malformed manifest digest) and semantic refusals (unsupported archive_schema_version).

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: BucketImportError

Raised when the encrypted payload member cannot be decrypted or fails integrity.

Distinct from SealedArchiveHeaderError so the operator sees a precise failure mode: a bad header is fixable upstream (re-export); a bad payload typically means the archive was tampered with or the wrong KEK / recovery passphrase was supplied.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: BucketExportError

Raised when the sealed archive cannot be written to the operator-specified path.

Covers IO errors (permission denied, disk full, target is a directory) at archive write time. The export service catches this and surfaces it through the CLI boundary’s command_error_boundary without retry.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]