cadrumo.adapters.persistence.profile.modelos_filing module

Encrypted SQL repository for the modelo filing-record catalogue.

ModeloRecordCatalogueRepository persists and loads ModeloRecord entries in a ModeloRecordCatalogue via SecureObjectRepository at FINANCIAL SensitivityClass using an Envelope wrapper. The catalogue is stored as a single encrypted BLOB per profile bucket.

This concrete repository is the persistence adapter behind the read-side ModeloRecordCatalogueRepositoryProtocol. It lives in the persistence adapter (not in modelos) because its secure-object coupling is SQL/crypto-bound; the domain package owns only the typed ModeloRecordCatalogue model and its pure mutators.

See also

adapters.persistence.profile._modelo_runtime

Bucket-id resolution and runtime secure-object factory shared by modelo persistence adapters.

ModeloRecordCatalogue

Domain catalogue payload encrypted by this repository.

ModeloRecordCatalogueRepositoryProtocol

Domain port this concrete persistence adapter implements.

MODELO_FILING_RECORD_CATALOGUE_NAMESPACE

Central namespace, sensitivity, schema-version, and singleton-key contract for these secure objects.

modelos_work_units

Sibling work-unit catalogue repository whose current/filed pointers reference filing records stored here.

file_modelo_revision()

Application service that writes local/internal filing state through the modelo catalogue repositories.

class ModeloRecordCatalogueRepository(*, bucket_id=None, objects=None)[source]

Bases: object

Repository over encrypted SQL-backed filing-record catalogue storage.

MODELO_FILING_RECORD_CATALOGUE_NAMESPACE is the central namespace, schema-version, sensitivity, and singleton-key contract for the encrypted ModeloRecordCatalogue row. The catalogue payload keeps member-scoped current/history lookups in the domain type. The write path (to_secure_object_write / save / exists) composes ProfileEnvelopedModelSecurePersistence for the shared Envelope-construction mechanic; load stays hand-rolled here because this repository translates a classification or schema-version mismatch into ModeloRecordPersistenceError via raise_catalogue_integrity_error(), a translation the shared kernel does not perform. This class exposes the concrete load/save implementation behind ModeloRecordCatalogueRepositoryProtocol.

Parameters:
property bucket_id: str | None

Profile bucket this repository reads from and writes to.

A bucket is the per-profile partition that isolates one taxpayer’s encrypted records from another’s. Returns the resolved bucket identifier, or None when the repository was constructed against an injected SecureObjectRepository and no bucket id was supplied.

exists()[source]

Report whether a persisted filing-record catalogue exists.

Returns True when an encrypted catalogue BLOB has already been written for this bucket, False otherwise. This is a presence check only; it neither decrypts nor validates the stored payload. Call load to retrieve and verify the catalogue contents.

Return type:

bool

load()[source]

Load and decrypt the filing-record catalogue from storage.

A modelo is an AEAT tax form, and each filing record is the durable receipt that a calculation revision (a dated, immutable result for that form) was filed for a given form, year, and period. The whole catalogue is persisted as one encrypted FINANCIAL-class BLOB and returned as a ModeloRecordCatalogue.

Returns an empty catalogue when nothing has been persisted yet.

Return type:

ModeloRecordCatalogue

Returns:

The decrypted ModeloRecordCatalogue for this bucket.

Raises:

ModeloRecordPersistenceError – If the stored envelope fails its sensitivity-class or schema-version integrity checks, or if its on-disk classification is not FINANCIAL, or if it was written at a schema version newer than this consumer supports.

save(catalogue)[source]

Persist the filing-record catalogue as a single encrypted BLOB.

Wraps catalogue in a FINANCIAL-class Envelope stamped with the current schema version and write timestamp, then writes it through the secure object store. The entire catalogue is rewritten as one encrypted object per bucket, replacing any prior catalogue for this bucket.

Parameters:

catalogue (ModeloRecordCatalogue) – The ModeloRecordCatalogue to encrypt and store.

Return type:

None

mutate(mutation)[source]

Apply mutation to the stored catalogue as one revision-guarded unit of work.

The catalogue is a SINGLETON row, so stamping one filing record rewrites every other. Performed unguarded, a record another caller wrote in the interim is discarded, and nothing reports it: the survivors are each intact and the missing one leaves no hole.

The bucket-ownership check runs on the mutation’s OWN result rather than once beforehand, so a mutation introducing a foreign record is refused on every attempt rather than only the first.

mutation is re-applied to the newly-current catalogue on a conflict, so it MUST be a pure function of what it is handed.

Return type:

ModeloRecordCatalogue

Parameters:

mutation (Callable[[ModeloRecordCatalogue], ModeloRecordCatalogue])

load_revisioned()[source]

Return the filing catalogue and the revision id it was read at.

The read a guarded co-commit needs: a caller composing this catalogue into a batch cannot use the self-committing mutate(), and without the revision its write puts the whole singleton row back over any filing record another writer added in between.

Return type:

tuple[ModeloRecordCatalogue, str]

to_secure_object_write(catalogue, *, expected_revision_id=None)[source]

Return the secure-object upsert for catalogue without committing it.

The returned SecureObjectWrite carries the same Envelope and SensitivityClass classification that save() would persist directly.

Pass expected_revision_id from load_revisioned() whenever the catalogue was DERIVED from a read; omitting it rewrites the row unconditionally.

Return type:

SecureObjectWrite

Parameters:
save_with_secure_object_writes(catalogue, extra_writes, *, expected_revision_id=None)[source]

Persist catalogue plus related secure objects in one unit of work.

Parameters:
Return type:

None