cadrumo.adapters.persistence.profile.prorrata_register module

Encrypted SQL persistence for the cross-period IVA prorrata register.

The domain.prorrata_register.register.ProrrataRegister document is stored as a FINANCIAL SensitivityClass secure object in the primary database through adapters.persistence.storage.sql.secure_objects.SecureObjectRepository. The singleton namespace, default object key, schema version, and custody contracts come from adapters.persistence.storage.secure_object_namespaces.PROFILE_PRORRATA_REGISTER_NAMESPACE.

The register is authoritative primary state (the taxpayer’s per-ejercicio provisional and settled prorrata percentages, seeded from the stamped prior settlement observation), not a rebuildable cache; it therefore carries a strict save/load/equality roundtrip plus an anti-tautology proof.

See also

domain.prorrata_register

Typed register payload models persisted here.

adapters.persistence.profile.bienes_inversion

Sibling profile-local secure-object adapter whose shape this mirrors.

class ProrrataRegisterRepository(*, bucket_id=None, objects=None)

Bases: object

Governed repository for the encrypted register singleton.

The singleton row is owned by adapters.persistence.storage.secure_object_namespaces.PROFILE_PRORRATA_REGISTER_NAMESPACE and persisted through adapters.persistence.storage.sql.secure_objects.SecureObjectRepository.

Parameters:

• bucket_id (str | None)

• objects (SecureObjectRepository | None)

property bucket_id: str | None

Return the explicit profile bucket identity, when one was supplied.

A repository constructed against an injected secure-object store cannot infer that store’s bucket safely; it deliberately remains unbound until the caller supplies bucket_id. Consumers that combine authorities from one filing bucket must reject that unbound shape rather than treating it as interchangeable with an explicitly owned register.

property envelope_path: Path

Logical path retained for callers that display the storage target.

load()

Load the register, returning an empty document when absent.

Return type:

ProrrataRegister

Returns:

Decrypted ProrrataRegister.

Raises:

ProrrataRegisterError – When the envelope exists but cannot be loaded or decrypted.

save(register)

Persist register as FINANCIAL-class ciphertext.

Parameters:

register (ProrrataRegister) – Register document to encrypt and write.

Return type:

None

load_revisioned()

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

The read a guarded co-commit needs: this register is composed into the calculate batch, so it cannot use a self-committing mutation, and an unguarded write puts the whole singleton row back over a sector entry another writer added in between.

Return type:

tuple[ProrrataRegister, str]

to_secure_object_write(register, *, expected_revision_id=None)

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

The filing persistence path co-emits the settled prorrata register with the filed revision and filing catalogue in one secure-object transaction, mirroring the participation-index write pattern.

Return type:

SecureObjectWrite

Parameters:

• register (ProrrataRegister)

• expected_revision_id (str | None)

upsert_entry(entry)

Atomically add or replace entry by its (ejercicio, sector_id) key.

The register carries one entry per (ejercicio, sector_id) key across the ejercicio’s lifecycle (provisional seed then definitive settlement), so declaring an entry for an existing key replaces it rather than raising.

The register is a singleton row, so this “add or replace one entry” is really read-whole-register, rebuild, write-whole-register. Run unguarded, two callers declaring entries for DIFFERENT keys both read the same register and the later save silently dropped the earlier caller’s entry – a lost update, invisible to the key-replacement logic because the two entries never met in one document.

The rebuild now runs through the shared revision-guarded unit of work, so a concurrent write makes it re-read and re-apply rather than overwrite.

Parameters:

entry (ProrrataRegisterEntry) – The entry to insert or update.

Return type:

ProrrataRegister

Returns:

The ProrrataRegister including the entry.

Raises:

SecureObjectRevisionConflictError – When contention persists across every attempt.

upsert_sector_definition(definition)

Atomically add or replace a differentiated-sector definition by its sector_id.

The register carries one SectorDefinition per sector_id (LIVA arts. 9.1.c / 101); declaring a sector whose id already exists replaces it rather than raising. Existing per-ejercicio entries are preserved, so the operator can declare the partition and the per-sector entries in either order.

Parameters:

definition (SectorDefinition) – The differentiated-sector partition entry to insert or update.

Return type:

ProrrataRegister

Carries the same revision guard as upsert_entry(), and for the same reason: the two methods write the SAME singleton row, so an unguarded sector declaration could discard a concurrently-declared entry just as easily as another sector definition.

Return type:

ProrrataRegister

Returns:

The updated ProrrataRegister including the definition.

Raises:

SecureObjectRevisionConflictError – When contention persists across every attempt.

Parameters:

definition (SectorDefinition)

upsert_activity_row(row)

Atomically add or replace one row by its (ejercicio, activity_id) key.

Return type:

ProrrataRegister

Parameters:

row (ProrrataActivityRow)