cadrumo.adapters.outbound.aeat.sede.observation_store module¶

Persistence helpers for read-only filed-declaration observations.

Persists each filed-declaration observation as an Envelope record through SecureObjectRepository, keyed by declaration identity so a prior filing can be retrieved without re-fetching it from the sede. Each envelope is classified at SensitivityClass FINANCIAL and encrypted under the authenticated bucket session’s own key, resolved through secure_object_repository_for_active_bucket(). The store takes no key material and no provider: it holds a taxpayer’s filed declarations, so the session that unwrapped the profile’s DEK is the only thing that may open them.

Artefact bytes are stored under adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_ARTEFACTS_NAMESPACE directly through SecureObjectRepository (a raw, digest-keyed blob with no Envelope wrapper – out of scope for the two families below). The two Envelope-wrapped observation families – adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE and adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE – are each a SecureBoundRepository subclass (FiledDeclaracionObservationRepository, IvaCompensationWalletObservationRepository): the natural-key derivation, envelope classification/version gate, and row-identity check that used to be hand-rolled here (~150 lines, and a row-identity check that raised its own SedeValidationError instead of the canonical SecureObjectRowIdentityError) now come from that shared base, with _translate_row_identity_error preserving this module’s domain-specific error type for the single-row load path. The base class has no translation hook for its enumeration path (iter_records/iter_ids raise SecureObjectRowIdentityError directly, unlike load), so FiledDeclaracionObservationStore’s list_* methods catch and translate it themselves rather than letting the untyped storage error leak through this module’s boundary.

filed_declaracion_observation_object_key(modelo, ejercicio, period, expediente_id)[source]¶

Return the secure-object natural key for a filed-declaration observation.

The key is the hash grammar declared by adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE.

Return type:

str

Parameters:

modelo (str)
ejercicio (int)
period (Period)
expediente_id (str)

iva_compensation_wallet_observation_object_key(taxpayer_nif, target_year, target_period, captured_at)[source]¶

Return the secure-object natural key for an IVA-wallet observation.

The key is the hash grammar declared by adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE.

Return type:

str

Parameters:

taxpayer_nif (str)
target_year (int)
target_period (Period)
captured_at (str)

class FiledDeclaracionObservationRepository(*, bucket_id=None, objects=None, settings=None)[source]¶

Bases: SecureBoundRepository[FiledDeclaracionObservation]

Envelope-bound repository for filed-declaration observations.

Governed by adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE. The natural key is the SHA-256 grammar filed_declaracion_observation_object_key() computes from a declaration’s identity fields; a row whose decrypted payload rebuilds a different key surfaces as SedeValidationError (the load path only – see the module docstring for why enumeration is handled separately).

Parameters:

bucket_id (str | None)
objects (SecureObjectRepository | None)
settings (Settings | None)

namespace: ClassVar[str]¶

sensitivity: ClassVar[SensitivityClass]¶

schema_version: ClassVar[int]¶

payload_type¶: alias of FiledDeclaracionObservation

extract_identifier(payload)[source]¶

Return the natural key payload claims to be filed under.

Return type:: str
Parameters:: payload (FiledDeclaracionObservation)

class IvaCompensationWalletObservationRepository(*, bucket_id=None, objects=None, settings=None)[source]¶

Bases: SecureBoundRepository[IvaCompensationWalletObservation]

Envelope-bound repository for read-only IVA compensation-wallet observations.

Governed by adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE. The natural key is the SHA-256 grammar iva_compensation_wallet_observation_object_key() computes from the wallet snapshot’s identity fields.

Parameters:

bucket_id (str | None)
objects (SecureObjectRepository | None)
settings (Settings | None)

namespace: ClassVar[str]¶

sensitivity: ClassVar[SensitivityClass]¶

schema_version: ClassVar[int]¶

payload_type¶: alias of IvaCompensationWalletObservation

extract_identifier(payload)[source]¶

Return the natural key payload claims to be filed under.

Return type:: str
Parameters:: payload (IvaCompensationWalletObservation)

class FiledDeclaracionObservationStore(root, *, objects=None)[source]¶

Bases: object

Persist captured AEAT filed data through encrypted SQL namespaces.

The store writes raw captured artefact bytes to adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_ARTEFACTS_NAMESPACE directly. FiledDeclaracionObservation and IvaCompensationWalletObservation persistence is delegated to FiledDeclaracionObservationRepository and IvaCompensationWalletObservationRepository respectively, both SecureBoundRepository subclasses bound to this store’s own secure-object backend.

Parameters:

root (Path)
objects (SecureObjectRepository | None)

persist_artefact(observation_key, artefact, body)[source]¶

Persist one captured artefact and return its FiledDeclaracionArtefact storage reference.

Artefact bytes are stored under adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_ARTEFACTS_NAMESPACE using the body SHA-256 as the natural object key.

Return type:

FiledDeclaracionArtefact

Parameters:

observation_key (tuple[str, int, Period, str])
artefact (FiledDeclaracionArtefact)
body (bytes)

load_artefact(storage_ref)[source]¶

Return plaintext artefact bytes from an encrypted storage reference.

The reference resolves into adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_ARTEFACTS_NAMESPACE.

The returned bytes are re-hashed and compared with the requested digest. A content address is a claim ABOUT bytes, and a claim nothing re-checks is only a lookup key: persist_artefact() verifies the digest on the way in, but the row could be overwritten afterwards under the same key, and the read then returned content that did not match the reference it was asked for. Decrypting proves custody of the bucket key; it says nothing about whether these are the bytes the reference names.

This is AEAT filing evidence, so a silent substitution is the failure that matters: the artefact is what a taxpayer would produce to defend a filed figure, and bytes that do not hash to their own reference cannot do that whatever they contain.

Raises:

ExpedienteNotFoundError – When no artefact is stored under the reference.
SedeValidationError – When the stored bytes do not hash to the requested digest.

Return type:

bytes

Parameters:

storage_ref (str)

persist_observation(observation, *, operation=None)[source]¶

Persist a normalized observation manifest and return its logical object path.

The envelope row is stored under adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE.

Return type:

Path

Parameters:

observation (FiledDeclaracionObservation)
operation (PinnedAuthorityOperation | None)

load_observation(path)[source]¶

Load and decrypt a FiledDeclaracionObservation from the encrypted store.

The encrypted row is read from adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE.

Return type:: FiledDeclaracionObservation
Parameters:: path (Path)

list_observations()[source]¶

Return FiledDeclaracionObservation records from the active encrypted backend.

Rows are scanned from adapters.persistence.storage.secure_object_namespaces.AEAT_FILED_DECLARATION_OBSERVATIONS_NAMESPACE.

Return type:: tuple[FiledDeclaracionObservation, ...]

persist_iva_wallet_observation(observation)[source]¶

Persist a read-only IVA wallet observation and return its logical path.

The envelope row is stored under adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE.

Return type:: Path
Parameters:: observation (IvaCompensationWalletObservation)

load_iva_wallet_observation(path)[source]¶

Load and decrypt an IvaCompensationWalletObservation from path.

The encrypted row is read from adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE.

Return type:: IvaCompensationWalletObservation
Parameters:: path (Path)

list_iva_wallet_observations()[source]¶

Return IvaCompensationWalletObservation records from the active encrypted backend.

Rows are scanned from adapters.persistence.storage.secure_object_namespaces.AEAT_IVA_WALLET_OBSERVATIONS_NAMESPACE.

Return type:: tuple[IvaCompensationWalletObservation, ...]