cadrumo.application.operations.financial_operand module

Runtime-only transient financial operand contracts for operation execution.

A transient financial operand is an amount an operator supplies while one operation is already running: a figure the executor needs once, that belongs to no ledger record and outlives nothing. It is deliberately not an ephemeral secret and not a persistent secure reference, and the three must not be collapsed.

An ephemeral secret is credential material the runtime holds under exact custody; a secure reference names bytes that live encrypted in the store. An operand is neither. It is a financial quantity with real declarative meaning - a currency, a scale, a bounded magnitude - which is exactly why it needs its own declaration rather than being smuggled through a secret port that treats its payload as opaque bytes.

The value never appears as a field on any model in this module. Every record here describes an operand - which one, for which interaction, until when, and what became of it - while the amount itself crosses only as a call argument, so there is no shape in this contract that a caller could serialize, log, or persist by accident.

Hashing is prohibited outright rather than discouraged. A digest of a financial amount over a known scale is not an anonymization: the domain is small enough to invert by enumeration, so a stored digest is a stored amount wearing a disguise. No record here carries a digest, fingerprint, or any other durable derivative of an operand.

See also

the ephemeral-secret broker path

The distinct one-shot port for credential material, not for amounts.

class OperationFinancialOperandRefusalReason(*values)

Bases: StrEnum

Why one operand wait ended without a delivered amount.

EXPIRED

CANCELLED

OUT_OF_DECLARED_RANGE

SCALE_NOT_REPRESENTABLE

UNKNOWN_REQUIREMENT

ALREADY_SETTLED

class OperationTransientFinancialOperandDeclaration(**data)

Bases: _OperandModel

Registry declaration of one operand an operation may ask for mid-flight.

The declaration is what makes an operand different from an opaque secret: it states the currency, the representable scale and the accepted magnitude up front, so a submitted amount can be refused on its own terms instead of failing somewhere inside the executor.

Parameters:

data (Any)

operand_kind: OperationFinancialOperandKind

currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

scale: Annotated[int, Field(ge=0, le=_MAX_OPERAND_SCALE)]

minimum: Decimal

maximum: Decimal

lifetime: timedelta

admits(amount)

Report whether one amount is representable and within the declared range.

Return type:

bool

Parameters:

amount (Decimal)

class OperationTransientFinancialOperandRequirement(**data)

Bases: _OperandModel

Durable identity of one exact runtime-only operand wait.

This record is safe to hold and to show: it names which operand an interaction is waiting for and until when, and carries no amount.

Parameters:

data (Any)

identity: OperationIdentity

interaction_id: OperationInteractionId

revision: OperationRevision

operand_kind: OperationFinancialOperandKind

expires_at: datetime

class OperationTransientFinancialOperandAcknowledgement(**data)

Bases: _OperandModel

Confirmation that one submitted operand was accepted into runtime custody.

Parameters:

data (Any)

outcome: Literal['accepted']

requirement: OperationTransientFinancialOperandRequirement

accepted_at: datetime

class OperationTransientFinancialOperandRefusal(**data)

Bases: _OperandModel

Refusal of one operand submission, naming the requirement it answered.

Parameters:

data (Any)

outcome: Literal['refused']

requirement: OperationTransientFinancialOperandRequirement

reason: OperationFinancialOperandRefusalReason

refused_at: datetime

class OperationTransientFinancialOperandExpiry(**data)

Bases: _OperandModel

Record that one operand wait lapsed before any amount arrived.

Parameters:

data (Any)

outcome: Literal['expired']

requirement: OperationTransientFinancialOperandRequirement

expired_at: datetime

class OperationTransientFinancialOperandRelease(**data)

Bases: _OperandModel

Record that runtime custody of one operand ended and its buffer was cleared.

Parameters:

data (Any)

outcome: Literal['released']

requirement: OperationTransientFinancialOperandRequirement

released_at: datetime

class OperationTransientFinancialOperandAccess(*args, **kwargs)

Bases: Protocol

Executor-only scoped read of the operand its own definition declared.

declared_operand(requirement)

Return the amount in custody for one requirement this executor owns.

Return type:

Decimal

Parameters:

requirement (OperationTransientFinancialOperandRequirement)