cadrumo.domain.modelos.protocols module

Domain-level repository Protocols for the modelos aggregate.

Application-layer code that persists or loads modelo work-unit catalogues, filing records, calculation results, or verification reports depends on these Protocols, not on the concrete adapter-backed repository classes. This keeps the domain layer free of adapter imports while still providing typed port surfaces.

The calculation-revision, filing-record, and verification-report protocols return CalculationRevisionCatalogue, ModeloRecordCatalogue, and VerificationReportCatalogue instances while keeping application code independent of concrete storage adapters. The work-unit port is defined directly in work_unit_repository.

class CalculationRevisionCatalogueRepositoryProtocol(*args, **kwargs)[source]

Bases: Protocol

Narrow domain-facing repository contract for calculation revisions.

Any object that provides exists, load, and save over a per-bucket CalculationRevisionCatalogue satisfies this protocol. The concrete secure-object-backed implementation is CalculationRevisionCatalogueRepository.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

exists()[source]

Return whether a calculation-revision catalogue object has been persisted.

Return type:

bool

load()[source]

Return the persisted catalogue or an empty catalogue if absent.

Return type:

CalculationRevisionCatalogue

Returns:

The CalculationRevisionCatalogue loaded from storage.

load_revisioned()[source]

Return the catalogue together with its current persistence revision.

Co-commit callers must carry this revision into their guarded write so rebuilding the singleton catalogue cannot overwrite a concurrent calculation revision.

Return type:

tuple[CalculationRevisionCatalogue, str]

save(catalogue)[source]

Persist catalogue as the encrypted singleton object.

Return type:

None

Parameters:

catalogue (CalculationRevisionCatalogue)

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

Return the SecureObjectWrite for catalogue without committing it.

expected_revision_id is the compare-and-swap half. These catalogues are SINGLETON rows, so a co-commit composed from an unguarded read writes the whole row back and discards any entry another caller added in between. It is declared HERE, not only on the concrete repository, because a caller typed against this protocol could otherwise not pass it at all – the guard existed and was unreachable.

Return type:

SecureObjectWrite

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

Persist catalogue plus co-emitted secure-object writes atomically.

Return type:

None

Parameters:
class ModeloRecordCatalogueRepositoryProtocol(*args, **kwargs)[source]

Bases: Protocol

Narrow domain-facing repository contract for modelo filing records.

Any object that provides exists, load, and save over a per-bucket ModeloRecordCatalogue satisfies this protocol. The concrete secure-object-backed implementation is ModeloRecordCatalogueRepository. The loaded catalogue supports member-scoped current_for and history_for lookups for grupo fan-in filings.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

exists()[source]

Return whether a modelo-record catalogue object has been persisted.

Return type:

bool

load()[source]

Return the persisted ModeloRecordCatalogue or an empty catalogue if absent.

Return type:

ModeloRecordCatalogue

load_revisioned()[source]

Return the catalogue and secure-object revision for guarded co-commit.

Return type:

tuple[ModeloRecordCatalogue, str]

save(catalogue)[source]

Persist catalogue as the encrypted singleton object.

Return type:

None

Parameters:

catalogue (ModeloRecordCatalogue)

mutate(mutation)[source]

Apply mutation to the stored catalogue as one revision-guarded unit of work.

On the port because the application needs it: the catalogue is a singleton row, so stamping one record rewrites every other, and doing that through save discards whatever a concurrent caller wrote.

Return type:

ModeloRecordCatalogue

Parameters:

mutation (Callable[[ModeloRecordCatalogue], ModeloRecordCatalogue])

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

Return the SecureObjectWrite for catalogue without committing it.

expected_revision_id is the compare-and-swap half. These catalogues are SINGLETON rows, so a co-commit composed from an unguarded read writes the whole row back and discards any entry another caller added in between. It is declared HERE, not only on the concrete repository, because a caller typed against this protocol could otherwise not pass it at all – the guard existed and was unreachable.

Return type:

SecureObjectWrite

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

Persist catalogue plus co-emitted secure-object writes atomically.

Return type:

None

Parameters:
class VerificationReportCatalogueRepositoryProtocol(*args, **kwargs)[source]

Bases: Protocol

Narrow domain-facing repository contract for verification reports.

Any object that provides exists, load, and save over a per-bucket VerificationReportCatalogue satisfies this protocol. The concrete secure-object-backed implementation is VerificationReportCatalogueRepository.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

exists()[source]

Return whether a verification-report catalogue object has been persisted.

Return type:

bool

load()[source]

Return the persisted catalogue or an empty catalogue if absent.

Return type:

VerificationReportCatalogue

Returns:

The VerificationReportCatalogue loaded from storage.

save(catalogue)[source]

Persist catalogue as the encrypted singleton object.

Return type:

None

Parameters:

catalogue (VerificationReportCatalogue)

class TransactionParticipationIndexRepositoryProtocol(*args, **kwargs)[source]

Bases: Protocol

Narrow domain-facing repository contract for the participation index.

The participation index is a per-transaction, derived-and-rebuildable read-side cache mapping a ledger transaction to the calculation revisions it participates in. Unlike the singleton catalogue repositories, its objects are keyed by transaction_id. Any object that provides exists, load, and save over a TransactionRevisionParticipationIndex satisfies this protocol; the concrete secure-object-backed implementation is TransactionParticipationIndexRepository. Lifecycle correctness never depends on this cache’s freshness — it is rebuilt from the revision catalogue — so the port is a navigation/read seam, not a source of truth.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

exists(transaction_id)[source]

Return whether a participation-index object exists for transaction_id.

Return type:

bool

Parameters:

transaction_id (str)

load(transaction_id)[source]

Return the persisted index for transaction_id or an empty index if absent.

Return type:

TransactionRevisionParticipationIndex

Parameters:

transaction_id (str)

save(index)[source]

Persist index as the encrypted per-transaction object.

Return type:

None

Parameters:

index (TransactionRevisionParticipationIndex)

to_secure_object_write(index)[source]

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

Return type:

SecureObjectWrite

Parameters:

index (TransactionRevisionParticipationIndex)