cadrumo.application.operations.owner module

Canonical owner-only invocation boundary for registered operation executors.

The supervisor supplies this context. Executors can publish typed facts and work with supervisor-owned resources through it, but cannot mutate the generic operation envelope or obtain concrete persistence and frontend adapters.

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

Bases: Protocol

Cooperative cancellation view controlled by the supervisor.

property cancellation_requested: bool

Whether the supervisor has requested a safe stop.

async acknowledge_cancellation()[source]

Record that the executor stopped at a cancellation-safe boundary.

Return type:

None

irreversible_section()[source]

Protect one executor-owned mutation boundary from an unsafe stop.

Return type:

AbstractAsyncContextManager[None]

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

Bases: Protocol

Read-only aggregate and cleanup deadlines supplied by the supervisor.

property execution_deadline: datetime | None

UTC aggregate execution deadline, or None when undeclared.

property cleanup_deadline: datetime | None

UTC cleanup-escalation deadline, or None when undeclared.

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

Bases: Protocol

Publish typed facts while leaving identity and ordering to the supervisor.

async phase(phase_code)[source]

Publish a transition to a definition-declared phase.

Return type:

None

Parameters:

phase_code (OperationEventCode)

async progress(*, completed, total, unit_code=None)[source]

Publish bounded unit progress.

Return type:

None

Parameters:

  • completed (int)

  • total (int)

  • unit_code (OperationEventCode | None)

async log(*, code, severity, diagnostic_ref=None)[source]

Publish a structured safe-log fact without prose or exceptions.

Return type:

None

Parameters:

  • code (OperationEventCode)

  • severity (OperationLogSeverity)

  • diagnostic_ref (OperationDiagnosticReference | None)

async effect(effect)[source]

Publish the executor’s current truthful effect fact.

Return type:

None

Parameters:

effect (OperationEffect)

async notice(notice_code)[source]

Publish a stable notice identity for frontend projection.

Return type:

None

Parameters:

notice_code (OperationEventCode)

async diagnostic(diagnostic_ref)[source]

Publish an opaque reference to canonical redacted diagnostics.

Return type:

None

Parameters:

diagnostic_ref (OperationDiagnosticReference)

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

Bases: Protocol

Persist and resolve confidential operands by canonical content digest.

async put(operand, *, written_at)[source]

Persist one typed operand in supervisor-owned secure storage.

Return type:

TypeAliasType

Parameters:

  • operand (BaseModel)

  • written_at (datetime)

async resolve(reference, operand_type)[source]

Return the validated operand of the requested application model type.

Return type:

TypeVar(OperandT, bound= BaseModel)

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

Bases: Protocol

Transfer asynchronous resource ownership to supervisor settlement.

own(resource, *, family)[source]

Register a resource that must close before terminal settlement.

Return type:

None

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

Bases: Protocol

Persist one definition-declared interaction checkpoint before yielding.

async publish_review(*, interaction_id, identity, revision, presentation_code, response_schema_ref, continuation_digest, expires_at, reviewed_operand, baseline_digest=None, proposed_effect_digest=None)[source]

Secure a typed reviewed operand before publishing its digest-bound checkpoint.

Return type:

None

Parameters:

  • interaction_id (str)

  • identity (OperationIdentity)

  • revision (OperationRevision)

  • presentation_code (OperationEventCode)

  • response_schema_ref (OperationReference)

  • continuation_digest (ContentDigest)

  • expires_at (datetime | None)

  • reviewed_operand (BaseModel)

  • baseline_digest (ContentDigest | None)

  • proposed_effect_digest (ContentDigest | None)

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

Bases: Protocol

Safe executor-facing view of one pending or consumed continuation.

property consumed: bool

Whether the continuation response has already been consumed.

property reviewed_proposal_digest: ContentDigest

Digest binding the checkpoint to its reviewed proposal.

property response_action: Literal[OperationResponseIntent.APPLY, OperationResponseIntent.REJECT] | None

Consumed response action, or None while still pending.

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

Bases: Protocol

Narrow capabilities available to one running operation executor.

property identity: OperationIdentity

Identity of the invocation receiving emitted facts and resources.

property revision: OperationRevision

Current authoritative revision for an exact successor transition.

property authority_operation: PinnedAuthorityOperation

Generation-pinned registry authority owned by the enclosing workflow.

property cancellation: OperationCancellationScope

Supervisor-owned cooperative cancellation scope.

property deadlines: OperationDeadlineAccess

Supervisor-owned aggregate and cleanup deadline view.

property events: OperationEventEmitter

Typed event boundary; executors never sequence or persist events.

property operands: OperationSecureOperandLookup

Secure lookup boundary for digest-addressed confidential operands.

property ephemeral_secret: OperationEphemeralSecretAccess

One-shot scoped secret access declared for this operation.

property financial_operand: OperationFinancialOperandContextAccess

Runtime-only transient financial operand surface for this operation.

property cleanup: OperationCleanupOwner

Resource ownership boundary settled by the supervisor.

property interactions: OperationInteractionAccess

Supervisor-owned typed interaction checkpoint boundary.

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

Bases: Protocol, Generic

Application-owned executor invoked only through the operation supervisor.

async execute(request, context)[source]

Run one request and return an optional domain-owned result reference.

Return type:

OperationReference | None

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

Bases: Protocol, Generic

Re-enter one declared pending-interaction checkpoint after owner recovery.

async resume(request, checkpoint, context)[source]

Resume from the exact durable checkpoint under a new supervisor lease.

Return type:

OperationReference | None

Parameters: