cadrumo.application.operations.financial_operand_submission module

Runtime custody broker for transient financial operands supplied mid-flight.

The broker owns nothing new. It composes the three pieces that already define what an operand is: the declaration and settlement contracts, the fixed custody order, and the durable checkpoint repository. Its whole job is to hold one amount in process memory between the operator submitting it and the executor reading it, and to make sure the durable record of that window is written before the amount is exposed rather than after.

The order of the durable writes is the load-bearing part. A submission that is accepted is journalled open, bound, and delivery-started in that order, all before the executor can read it, so a process that dies while the executor holds the amount reconciles as delivery-uncertain. Writing the checkpoints after the read would let the same crash reconcile as not-delivered, which is a manufactured claim that the executor never saw a figure it may well have acted on.

Nothing here stores an amount anywhere but a private mapping, and nothing here returns a durable derivative of one. The value leaves only through OperationTransientFinancialOperandBroker.grant_access(), scoped to the executor that declared it.

See also

the transient financial operand broker

The broker contract this class implements.

EphemeralSecretBroker

The sibling broker for credential material, deliberately separate.

financial_operand_interaction_id(*, identity, revision, operand_kind)

Derive the one interaction identifier a declared operand wait is addressed by.

The derivation is deterministic so an operator frontend can address the wait it is answering without the executor having to hand it a handle first, and so a redeclaration inside the executor names the same wait.

Return type:

TypeAliasType

Parameters:

• identity (OperationIdentity)

• revision (OperationRevision)

• operand_kind (OperationFinancialOperandKind)

class OperationFinancialOperandContextAccess(*args, **kwargs)

Bases: Protocol

The operand surface an executor context exposes for one invocation.

declare_requirement(declaration)

Open the bounded wait for one operand this definition declared.

Return type:

OperationTransientFinancialOperandRequirement

Parameters:

declaration (OperationTransientFinancialOperandDeclaration)

grant_access(requirement)

Return scoped access to the amount accepted for one requirement.

Return type:

OperationTransientFinancialOperandAccess

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

class GrantedTransientFinancialOperandAccess(*, requirement, broker)

Bases: object

Executor-scoped read of one accepted operand, bound to its requirement.

Parameters:

• requirement (OperationTransientFinancialOperandRequirement)

• broker (OperationTransientFinancialOperandBroker)

property requirement: OperationTransientFinancialOperandRequirement

Return the exact requirement this access was granted for.

declared_operand(requirement)

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

Return type:

Decimal

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

class BoundTransientFinancialOperandAccess(*, declarations, broker, identity, revision)

Bases: object

The one operand surface an executor sees, scoped to its own invocation.

The executor names a declaration its definition already carries; the identity, revision and derived interaction identifier come from the supervisor, so an executor cannot open a wait against another invocation or against an operand kind it never declared.

Parameters:

• declarations (tuple[OperationTransientFinancialOperandDeclaration, ...])

• broker (OperationTransientFinancialOperandBroker | None)

• identity (OperationIdentity)

• revision (OperationRevision)

declare_requirement(declaration)

Open the bounded wait for one operand this definition declared.

Return type:

OperationTransientFinancialOperandRequirement

Parameters:

declaration (OperationTransientFinancialOperandDeclaration)

grant_access(requirement)

Return scoped access to the amount accepted for one requirement.

Return type:

GrantedTransientFinancialOperandAccess

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

class OperationTransientFinancialOperandBroker(*, custody, clock)

Bases: object

Supervisor-private operand custody over a durable checkpoint repository.

Parameters:

• custody (OperationFinancialOperandCustodyRepository)

• clock (Callable[[], datetime])

declare_requirement(declaration, *, identity, interaction_id, revision)

Open one bounded wait for the operand this declaration describes.

Redeclaring the same wait returns the requirement already open rather than restarting its lifetime, so an executor and an operator frontend that both address the wait cannot disagree about when it lapses.

Return type:

OperationTransientFinancialOperandRequirement

Parameters:

• declaration (OperationTransientFinancialOperandDeclaration)

• identity (OperationIdentity)

• interaction_id (OperationInteractionId)

• revision (OperationRevision)

async deliver(requirement, amount, *, observed_at)

Settle one submission against the declaration that opened its wait.

The durable checkpoints are written here, before the amount becomes readable, and the wait is journalled open whether the submission is accepted or refused so a refused wait is still reconcilable.

Return type:

TypeAliasType

Parameters:

• requirement (OperationTransientFinancialOperandRequirement)

• amount (Decimal)

• observed_at (datetime)

grant_access(requirement)

Return executor-scoped access to one accepted operand.

Return type:

GrantedTransientFinancialOperandAccess

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

read_operand(requirement)

Return the amount held for one requirement, refusing a released wait.

Return type:

Decimal

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

release(requirement)

End runtime custody of one operand and clear the buffer holding it.

Return type:

OperationTransientFinancialOperandRelease

Parameters:

requirement (OperationTransientFinancialOperandRequirement)

expire_lapsed(*, now)

Settle every wait whose declared lifetime has elapsed.

Return type:

tuple[OperationTransientFinancialOperandExpiry, ...]

Parameters:

now (datetime)

async settle(requirement, *, now)

Acknowledge delivery durably, then end runtime custody exactly once.

Return type:

OperationTransientFinancialOperandRelease

Parameters:

• requirement (OperationTransientFinancialOperandRequirement)

• now (datetime)

async settle_operation(operation_id, *, now)

Settle every wait one finished operation still holds.

Return type:

None

Parameters:

• operation_id (OperationId)

• now (datetime)

async reconcile_owner_restart(*, now)

Settle every durable wait an earlier process left unfinished.

Return type:

tuple[OperationFinancialOperandCustodyCheckpoint, ...]

Parameters:

now (datetime)

close()

Drop every held amount and refuse further declarations.

Return type:

None