cadrumo.application.operations.persistence.financial_operand_custody module

Durable custody-checkpoint persistence contract for financial operands.

The repository stores the checkpoints defined by the operand custody contract and nothing else. Its guarantee is narrow and load-bearing: an advance is accepted only when it follows the predecessor the caller actually observed, so two supervisor paths racing to settle one wait cannot both win.

That compare-and-swap is what makes release exactly-once at the durable layer rather than only in memory. The in-process transition table refuses an illegal move; this refuses a legal move applied twice.

See also

OperationFinancialOperandCustodyCheckpoint

The non-sensitive record this contract persists and replays.

exception OperationFinancialOperandCustodyConflictError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a custody advance loses its compare-and-swap.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class OperationFinancialOperandCustodyRepository(*args, **kwargs)[source]

Bases: Protocol

Persist and replay one operand wait’s custody positions.

async read(interaction_id)[source]

Return the latest checkpoint for one wait, or None if never opened.

Return type:

OperationFinancialOperandCustodyCheckpoint | None

Parameters:

interaction_id (str)

async open(checkpoint)[source]

Record the opening checkpoint, refusing a wait that already exists.

Return type:

None

Parameters:

checkpoint (OperationFinancialOperandCustodyCheckpoint)

async advance(predecessor, successor)[source]

Replace predecessor with successor only if it is still current.

Raises:

OperationFinancialOperandCustodyConflictError – The stored checkpoint is no longer predecessor, so another path already settled or advanced this wait.

Return type:

None

Parameters:
async unsettled()[source]

Return every wait left in a non-terminal state, for restart reconciliation.

Return type:

tuple[OperationFinancialOperandCustodyCheckpoint, ...]