cadrumo.adapters.persistence.profile.buckets module

Encrypted SQL repository for the bucket-event-history catalogue.

BucketEventHistoryRepository persists BucketEventHistoryCatalogue through SecureObjectRepository, which handles encrypted BLOB storage and key management for the active profile bucket. Each stored record is wrapped in an Envelope at FINANCIAL SensitivityClass.

The write path (to_secure_object_write / save / exists) composes ProfileEnvelopedModelSecurePersistence for the shared envelope-construction mechanic. The read path (load / load_revisioned) stays hand-rolled here rather than routing through the shared kernel’s generic checks: this repository’s classification and schema-version mismatch errors carry a richer, test-asserted translated_message/context shape distinguishing an outer (SQL-row) integrity failure from an inner (envelope-payload) classification or version drift, plus a dedicated schema-drift (ValidationError) translation none of that is part of the shared kernel’s generic contract, and collapsing it would be a silent, observable error-message regression for every caller and test that depends on the specific translated message.

This concrete repository is the persistence adapter behind the read-side BucketEventHistoryRepositoryProtocol. It lives in the persistence adapter (not in buckets) because its secure-object coupling is SQL/crypto-bound; the domain package owns only the typed BucketEventHistoryCatalogue model, its narrow port, and the BucketEventHistoryPersistenceError 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

buckets

Public bucket-event facade that owns the catalogue, event taxonomy, and repository protocol.

BucketEventHistoryCatalogue

Domain payload encrypted by this repository.

BucketEventHistoryRepositoryProtocol

Domain port this concrete persistence adapter implements.

BUCKET_EVENT_HISTORY_NAMESPACE

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

secure_object_repository_for_active_bucket()

Runtime storage factory used when no secure-object repository is injected.

bucket_maintenance

Application lifecycle surface that records bucket-maintenance events through this repository.

class BucketEventHistoryRepository(*, objects=None)

Bases: object

Repository over encrypted SQL-backed event-history catalogue storage.

BUCKET_EVENT_HISTORY_NAMESPACE is the central profile-local namespace, schema-version, sensitivity, and singleton-key contract for the encrypted BucketEventHistoryCatalogue. The catalogue preserves the append-only BucketEvent history, is wrapped in Envelope, and is persisted through SecureObjectRepository. The same envelope can be emitted as a SecureObjectWrite when sibling catalogue updates need one transaction. This class exposes the concrete load/save implementation behind BucketEventHistoryRepositoryProtocol, composing ProfileEnvelopedModelSecurePersistence for the write-path envelope mechanic (see module docstring for why the read path stays separate).

Parameters:

objects (SecureObjectRepository | None)

property secure_object_repository: SecureObjectRepository

Return the secure-object backend used by this catalogue.

Returns:

The SecureObjectRepository backing this repository.

exists()

Return whether a bucket-event-history catalogue has been persisted.

Return type:

bool

load()

Return the persisted catalogue or an empty catalogue if absent.

Return type:

BucketEventHistoryCatalogue

Returns:

The deserialised BucketEventHistoryCatalogue, or a fresh empty instance when no database object is present.

Raises:

BucketEventHistoryPersistenceError – If secure-object classification, envelope version, or payload validation fails.

load_revisioned()

Load the catalogue and the exact secure-object revision observed.

Return type:

tuple[BucketEventHistoryCatalogue, str]

save(catalogue)

Persist catalogue atomically through the secure-object repository.

Parameters:

catalogue (BucketEventHistoryCatalogue) – The BucketEventHistoryCatalogue to persist.

Return type:

None

append_guarded(appender, *, attempts=4)

Append through appender as one revision-guarded unit of work.

The event history is a SINGLETON row, so appending one event rewrites the whole catalogue. Performed unguarded, two callers recording DIFFERENT transitions both read the same catalogue and the later write discards the earlier event. Nothing detects it: the events are content-addressed, so the survivors all look internally consistent and the missing one leaves no gap to notice. On an append-only audit trail that is the worst shape of loss – the record reads as complete.

The write carries the revision the catalogue was READ at, so the substrate refuses it if the row moved, and appender is re-applied to the newly-current catalogue. It is therefore called once per attempt and MUST be a pure function of what it is handed.

Parameters:

• appender (Callable[[BucketEventHistoryCatalogue], BucketEventHistoryCatalogue]) – Builds the next catalogue from the current one.

• attempts (int) – Maximum reads before the contention is surfaced.

Return type:

BucketEventHistoryCatalogue

Returns:

The catalogue as written.

Raises:

SecureObjectRevisionConflictError – Contention persisted across every attempt.

to_secure_object_write(catalogue, *, expected_revision_id=None)

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.

Return type:

SecureObjectWrite

Parameters:

• catalogue (BucketEventHistoryCatalogue)

• expected_revision_id (str | None)

build_bucket_event_history_repository(*, bucket_id)

Build the encrypted event-history repository for bucket_id.

Return type:

BucketEventHistoryRepository

Parameters:

bucket_id (str)