cadrumo.adapters.persistence.profile.modelos_calculation module¶

Encrypted SQL repository for the calculation-revision catalogue.

CalculationRevisionCatalogueRepository persists and loads CalculationRevision records in a CalculationRevisionCatalogue via SecureObjectRepository at FINANCIAL SensitivityClass. Each catalogue is wrapped in Envelope before being written to the encrypted BLOB per profile bucket.

This concrete repository is the persistence adapter behind the read-side CalculationRevisionCatalogueRepositoryProtocol. 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 CalculationRevisionCatalogue model, the pure upsert_calculation_revision() mutator, and the CalculationRevisionPersistenceError boundary error. The namespace/version constants are redeclared here as the persisted-envelope contract; the strings are preserved to avoid orphaning persisted envelopes.

See also

adapters.persistence.profile._modelo_runtime: Bucket-id resolution and runtime secure-object factory shared by modelo persistence adapters.
CalculationRevisionCatalogue: Domain catalogue payload encrypted by this repository.
CalculationRevisionCatalogueRepositoryProtocol: Domain port this concrete persistence adapter implements.
MODELO_CALCULATION_REVISION_CATALOGUE_NAMESPACE: Central namespace, sensitivity, schema-version, and singleton-key contract for these secure objects.
SecureObjectRepository: Runtime-created encrypted storage boundary used for load/save.

Core types: RegistrySnapshot.

class CalculationRevisionCatalogueRepository(*, bucket_id=None, objects=None, m303_rectificativa_taxpayer_tax_id=None)[source]¶

Bases: object

Repository over encrypted SQL-backed calculation-revision catalogue storage.

MODELO_CALCULATION_REVISION_CATALOGUE_NAMESPACE is the central namespace, schema-version, sensitivity, and singleton-key contract for the encrypted CalculationRevisionCatalogue row. The write path (to_secure_object_write / save / exists) composes ProfileEnvelopedModelSecurePersistence for the shared Envelope-construction mechanic; load stays hand-rolled here because it translates a classification or schema-version mismatch into CalculationRevisionPersistenceError via raise_catalogue_integrity_error(), and runs the post-load ledger-evidence coverage gate (assert_revision_snapshot_evidence_coverage()) the shared kernel has no domain knowledge of. The class exposes the concrete load/save implementation behind CalculationRevisionCatalogueRepositoryProtocol.

Parameters:

bucket_id (str | None)
objects (SecureObjectRepository | None)
m303_rectificativa_taxpayer_tax_id (SubjectTaxId | None)

property bucket_id: str | None¶

Identifier of the per-profile storage bucket this repository reads and writes.

A modelo (an AEAT tax form or declaration) carries calculation revisions per filing profile, and each profile owns its own encrypted bucket. This property exposes the resolved bucket identifier, or None when the repository was constructed against a caller-supplied SecureObjectRepository rather than a resolved bucket.

Returns:: The trimmed bucket identifier, or None when no bucket was resolved.

exists()[source]¶

Report whether a calculation-revision catalogue has been persisted.

Checks the encrypted store for an object under this repository’s namespace and key without decrypting or validating it, so a True result attests to presence only, not integrity.

Return type:: bool
Returns:: True when a stored catalogue object exists, False otherwise.

load(*, operation=None)[source]¶

Load and decrypt the persisted calculation-revision catalogue.

A calculation revision is a dated, computed version of a modelo’s casilla values (a casilla is a numbered box on an AEAT form); the catalogue is the keyed collection of those revisions. The stored record is decrypted, its Envelope parsed, and its sensitivity classification and schema version checked before the payload is returned. When nothing has been persisted yet, an empty CalculationRevisionCatalogue is returned rather than raising.

Return type:: CalculationRevisionCatalogue
Returns:: The persisted CalculationRevisionCatalogue, or an empty one when no record exists.
Raises:: ~CalculationRevisionPersistenceError – If the stored record fails the FINANCIAL classification check, or its envelope schema version exceeds the version this consumer supports, or an integrity error surfaces while decrypting and decoding the record.
Parameters:: operation (PinnedAuthorityOperation | None)

save(catalogue)[source]¶

Persist the calculation-revision catalogue to encrypted storage.

Wraps the catalogue (the keyed collection of a modelo’s dated calculation revisions) in an Envelope stamped with the current schema version, write time, and FINANCIAL sensitivity classification, then writes the serialised envelope to the encrypted store under this repository’s namespace and key. An existing catalogue object at that location is overwritten.

Parameters:: catalogue (CalculationRevisionCatalogue) – The CalculationRevisionCatalogue to serialise and store.
Return type:: None

load_revisioned(*, operation=None)[source]¶

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

The read a guarded co-commit needs. A calculate run composes this catalogue with the work-unit catalogue and the creation event in one unit of work, so it cannot use a self-committing mutation, and without the revision it would write back the whole catalogue and discard a revision another run added in between. A dropped calculation revision is a dropped tax computation.

Raises:: ~CalculationRevisionPersistenceError – If the stored payload fails the catalogue contract, exactly as load() refuses it, so no raw validation detail reaches the caller.
Return type:: tuple[CalculationRevisionCatalogue, str]
Parameters:: operation (PinnedAuthorityOperation | None)

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. It can be co-emitted with related secure objects (e.g. the participation index) in one save_with_secure_object_writes() unit of work.

Pass expected_revision_id from load_revisioned() whenever the catalogue was DERIVED from a read; omitting it writes the whole singleton row back unconditionally.

Return type:

SecureObjectWrite

Parameters:

catalogue (CalculationRevisionCatalogue)
expected_revision_id (str | None)

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

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

The catalogue save and every extra write land or fail together in a single SQL transaction, so the participation index co-emitted here can never drift from the calculation revision it indexes (per the composition-service single-writer discipline).

Parameters:

catalogue (CalculationRevisionCatalogue) – The CalculationRevisionCatalogue to persist.
extra_writes (tuple[SecureObjectWrite, ...]) – Additional SecureObjectWrite objects to commit atomically with the catalogue.
expected_revision_id (str | None) – The revision load_revisioned() reported for the catalogue this one was derived from. Atomicity is what this method already gave; without the revision it still writes the whole singleton row back, so a revision another calculate run added between the read and this call is discarded – and a dropped calculation revision is a dropped tax computation. Omit only when the catalogue was not derived from a read.

Return type:

None