cadrumo.adapters.persistence.profile.modelos_work_units module¶

Encrypted SQL repository for the modelo work-unit catalogue.

WorkUnitCatalogueRepository persists WorkUnit records in a WorkUnitCatalogue at FINANCIAL SensitivityClass through SecureObjectRepository. The catalogue is serialised as a single Envelope-wrapped JSON payload keyed by a stable namespace and object key; the underlying column is encrypted so no plaintext work-unit metadata lands on disk.

This concrete repository is the persistence adapter behind the read-side WorkUnitCatalogueRepositoryProtocol. 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 WorkUnitCatalogue model and its pure catalogue mutators.

See also

adapters.persistence.profile._modelo_runtime: Bucket-id resolution and runtime secure-object factory shared by modelo persistence adapters.
WorkUnitCatalogue: Domain catalogue payload encrypted by this repository.
WorkUnitCatalogueRepositoryProtocol: Domain port this concrete persistence adapter implements.
MODELO_WORK_UNIT_CATALOGUE_NAMESPACE: Central namespace, sensitivity, schema-version, and singleton-key contract for these secure objects.
modelos_calculation: Sibling calculation-revision repository referenced by work-unit current and verification lifecycle state.
modelo: Application facade that creates, calculates, verifies, files, and exports work units from this catalogue.

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

Bases: object

Repository over encrypted SQL-backed work-unit catalogue storage.

A single envelope-wrapped catalogue object holds every work unit. Loads return an empty catalogue when no object has been persisted yet (no separate “fresh install” path is needed). The write path (to_secure_object_write / save / exists) composes ProfileEnvelopedModelSecurePersistence for the shared one-record decode and Envelope-construction mechanics; load_revisioned() translates a classification or schema-version mismatch into WorkUnitPersistenceError via raise_catalogue_integrity_error(). This class is the concrete implementation behind WorkUnitCatalogueRepositoryProtocol.

Parameters:

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

property bucket_id: str | None¶: Return the profile bucket id when this repository resolved one.

exists()[source]¶

Return whether a work-unit catalogue object has been persisted.

Return type:: bool

load()[source]¶

Return the persisted catalogue or an empty catalogue if absent.

Return type:: WorkUnitCatalogue
Returns:: The deserialised WorkUnitCatalogue, or an empty instance when no object has been persisted yet.
Raises:: WorkUnitPersistenceError – When the persisted envelope’s classification or schema version disagrees with the consumer’s contract.

save(catalogue)[source]¶

Persist catalogue as the encrypted singleton object.

The on-disk database value is an encrypted Envelope BLOB at the SensitivityClass FINANCIAL classification.

Parameters:: catalogue (WorkUnitCatalogue) – The WorkUnitCatalogue to persist.
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 touching one work unit rewrites all of them. Performed unguarded, a work unit created or advanced by a concurrent caller is discarded by whichever write lands second, and nothing reports it: the surviving entries are individually intact and the missing one leaves no hole.

mutation is re-applied to the newly-current catalogue on a conflict, so it MUST be a pure function of the catalogue it is handed – a decision closed over from an earlier read would be replayed against a catalogue it was never true of.

Return type:: WorkUnitCatalogue
Parameters:: mutation (Callable[[WorkUnitCatalogue], WorkUnitCatalogue])

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

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

Lets a caller advance the work-unit pointer in the SAME unit of work as the calculation, filing, and event catalogues the pointer names, so a failure cannot leave an advanced pointer standing over state that never committed. The returned SecureObjectWrite carries the same Envelope and SensitivityClass classification save() would persist directly.

Return type:

SecureObjectWrite

Parameters:

catalogue (WorkUnitCatalogue)
expected_revision_id (str | None)

load_revisioned()[source]¶

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

The read a guarded co-commit needs. A lifecycle transition composes this catalogue with the event that records it, so it cannot use the self-committing mutate(), and without the revision its batch rewrites the whole singleton row over a unit another caller created.

Return type:: tuple[WorkUnitCatalogue, str]

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. A work-unit lifecycle transition that saved the catalogue and emitted its bucket event afterwards could come to rest durable-but-unrecorded: the created, renamed, or discarded unit survived while the history had no matching entry and no marker named the gap. Folding the event’s write in here puts the state and its promised event in one transaction, so neither can land without the other.

Parameters:

catalogue (WorkUnitCatalogue) – The WorkUnitCatalogue 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 the batch already gave; the revision is what stops it writing the whole singleton row back over a work unit another caller created between the read and this call.

Return type:

None