cadrumo.adapters.persistence.profile.participation_index module

Encrypted persistence for the transaction-to-revision participation index.

The participation index is a derived, rebuildable read-side cache linking one ledger transaction id to the finalized modelo revisions, filings, and justificantes that consumed it. This concrete repository is the persistence adapter behind the pure modelos index model: it stores one Envelope per transaction at SensitivityClass FINANCIAL under the active profile bucket, mirroring the CalculationRevision catalogue repository.

Living in the persistence adapter (not in modelos) keeps the SecureObjectRepository / Envelope coupling out of the domain layer; the domain package owns only the typed index model, its derivation, and the object-key grammar. The index is critically sensitive financial data; no plaintext index is ever written to disk.

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

Bases: object

Read / write one transaction’s participation index in encrypted storage.

Mirrors the CalculationRevision catalogue repository: persistence is delegated to SecureObjectRepository at SensitivityClass FINANCIAL under the active profile bucket, one secure object per transaction_id. The participation index is critically sensitive financial data (it links a ledger transaction to its filings); no plaintext index is ever written to disk.

Parameters:

• bucket_id (str | None)

• objects (SecureObjectRepository | None)

property bucket_id: str | None

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

property secure_object_repository: SecureObjectRepository

Return the SecureObjectRepository backend.

exists(transaction_id)

Report whether a participation index has been persisted for transaction_id.

Return type:

bool

Parameters:

transaction_id (str)

load(transaction_id)

Load and decrypt one transaction’s persisted participation index.

Returns an empty TransactionRevisionParticipationIndex for that transaction when nothing has been persisted yet, rather than raising.

The decrypted payload’s own transaction_id must rebuild the key the row is filed under. It is the same fact twice – to_secure_object_write() derives the key FROM the payload, so the write path cannot disagree with itself and needs no check; only a row that arrived some other way can. Without the comparison, an index belonging to transaction B read through A’s key attributed B’s finalized-revision participations to A, which is what the ledger deletion guard and the operator cross-reference both read.

Raises:

• TransactionParticipationIndexPersistenceError – The stored row fails the classification or envelope-version gate.

• SecureObjectRowIdentityError – The payload names a different transaction than the key it is filed under. Raised as the substrate’s own identity error rather than translated, so this condition is the one recognisable failure across every key-addressed repository instead of a per-repository dialect.

Return type:

TransactionRevisionParticipationIndex

Parameters:

transaction_id (str)

save(index)

Persist one transaction’s participation index to encrypted storage.

Return type:

None

Parameters:

index (TransactionRevisionParticipationIndex)

replace_all(indexes)

Atomically make indexes the complete persisted participation index.

The participation index is a derived cache whose authority is the calculation-revision catalogue, so a regeneration must be a replace, not an upsert: a transaction whose last finalized revision was discarded or removed has no entry in the regenerated set, and its stale secure object must disappear with it. Upserting only the regenerated rows would leave that object readable through load() / exists(), letting the derived cache surface participations the authoritative catalogue no longer records.

Every upsert and every stale-row removal commits in one apply_batch() unit of work, so a crash mid-replace rolls back to the previous complete index rather than a half-pruned one.

Stale rows are addressed by their stored HMAC digest: natural object keys are unrecoverable from the index (see list_keys()), so the retained set is digested with the same secure_object_key_digest the storage column binds with and the difference is deleted by digest. This keeps the prune decryption-free.

Return type:

int

Returns:

The number of stale participation objects removed.

Parameters:

indexes (Iterable[TransactionRevisionParticipationIndex])

to_secure_object_write(index)

Return the SecureObjectWrite upsert for index without committing it.

Mirrors the bucket-event-history repository so the participation write can be passed to save_with_secure_object_writes as an extra write slot, co-emitting atomically with the revision save.

Return type:

SecureObjectWrite

Parameters:

index (TransactionRevisionParticipationIndex)