cadrumo.application.operations.projection_services module

Canonical safe projection and public operation-control services.

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

Bases: Protocol

Narrow mutation port implemented by the canonical operation supervisor.

async request_cancel(operation_id, *, expected_revision)[source]

Request cooperative cancellation at one expected revision.

Return type:

OperationPersistedSnapshot

Parameters:

  • operation_id (OperationId)

  • expected_revision (int)

async detach(operation_id)[source]

Detach the caller while retaining the durable operation state.

Return type:

OperationPersistedSnapshot

Parameters:

operation_id (OperationId)

async respond(response)[source]

Consume one validated REVIEW response.

Return type:

OperationConsumedInteraction

Parameters:

response (OperationApplyResponse | OperationRejectResponse)

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

Bases: Protocol

Runtime-only authority for separately held REVIEW response capabilities.

async permitted_intents(request, pending, /)[source]

Return the response intents authorized for an exact pending review.

Return type:

frozenset[OperationResponseIntent]

Parameters:
async response_token(request, pending, intent, /)[source]

Return the opaque token only for one authorized response intent.

Return type:

TypeAliasType

Parameters:
close()[source]

Irreversibly close and wipe this runtime-only authority.

Return type:

None

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

Bases: Protocol

Runtime-only sink for one freshly published REVIEW bearer.

issue(pending, response_token)[source]
Return type:

None

Parameters:
class BoundOperationSecureResponseAuthority(operation_id, interaction_id, revision, reviewed_proposal_digest, actor_ref, expires_at, intents, clock, _token)[source]

Bases: object

One runtime-only bearer bound to an exact pending REVIEW decision.

Parameters:
operation_id: TypeAliasType
interaction_id: TypeAliasType
revision: int
reviewed_proposal_digest: TypeAliasType
actor_ref: TypeAliasType
expires_at: datetime | None
intents: frozenset[OperationResponseIntent]
clock: Callable[[], datetime]
classmethod bind(*, operation_id, interaction_id, revision, reviewed_proposal_digest, actor_ref, expires_at, intents, response_token, clock)[source]

Bind one mutable bearer to an exact pending REVIEW decision.

Return type:

Self

Parameters:
async permitted_intents(request, pending, /)[source]

Validate the binding and return its still-permitted response intents.

Return type:

frozenset[OperationResponseIntent]

Parameters:
async response_token(request, pending, intent, /)[source]

Return the private token only after exact authority validation.

Return type:

TypeAliasType

Parameters:
close()[source]

Zeroize the in-memory response bearer and prevent reuse.

Return type:

None

class UnavailableOperationSecureResponseAuthority[source]

Bases: object

async permitted_intents(request, pending, /)[source]
Return type:

frozenset[OperationResponseIntent]

Parameters:
async response_token(request, pending, intent, /)[source]
Return type:

TypeAliasType

Parameters:
close()[source]

Close the empty authority idempotently.

Return type:

None

class OperationResponseCapability(operation_id, actor_ref, handle, *, _issuer)[source]

Bases: object

Opaque process-local capability retained separately from observation.

Parameters:

  • operation_id (OperationId)

  • actor_ref (OperationActorReference)

  • handle (bytearray)

  • _issuer (object)

matches(operation_id, actor_ref, capability_digest)[source]
Return type:

bool

Parameters:

  • operation_id (OperationId)

  • actor_ref (OperationActorReference)

  • capability_digest (ContentDigest)

close()[source]

Irrevocably release this caller-held response capability.

Return type:

None

class OperationResponseAuthorityBroker[source]

Bases: OperationResponseAuthorityBrokerMixin

Process-local REVIEW bearer custody that cannot survive restart.

class OperationReviewProjectionService(reader, registry, operands, clock)[source]

Bases: object

Resolve safe public REVIEW projections from durable operation state.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
operands: OperationSecureReferenceStore
clock: Callable[[], datetime]
async resolve(request)[source]

Resolve the exact registered REVIEW projection or a typed refusal.

Return type:

GenericAlias[TypeVar(ReviewProjectionT, bound= BaseModel)]

Parameters:

request (OperationReviewProjectionVersionHeader | OperationReviewProjectionRequestV1)

class OperationWorkspaceRefreshTargetService(reader, registry)[source]

Bases: object

Resolve safe typed workspace refresh targets after terminal success.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
async resolve(request)[source]

Resolve the exact registered refresh target or a typed refusal.

Return type:

GenericAlias[TypeVar(RefreshTargetT, bound= BaseModel)]

Parameters:

request (OperationWorkspaceRefreshTargetVersionHeader | OperationWorkspaceRefreshTargetRequestV1)

class OperationResultProjectionService(reader, registry, operands)[source]

Bases: object

Resolve safe public settled-result projections after terminal success.

Symmetric with OperationReviewProjectionService: the private settled result is resolved behind the secure operand port and handed, with the safe terminal receipt, to the registered domain projector. The private result type never crosses this boundary; only the projector’s typed public output does.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
operands: OperationSecureReferenceStore
async resolve(request)[source]

Resolve the exact registered public result projection or a refusal.

Return type:

GenericAlias[TypeVar(ResultProjectionT, bound= BaseModel)]

Parameters:

request (OperationResultProjectionVersionHeader | OperationResultProjectionRequestV1)

class OperationResponseControlService(reader, registry, authority, supervisor)[source]

Bases: object

Inspect and execute safe REVIEW response control at the public boundary.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
authority: OperationSecureResponseAuthority
supervisor: OperationControlSupervisor
async inspect(request)[source]

Return authorized response intents or a typed refusal.

Return type:

TypeAliasType

Parameters:

request (OperationResponseControlVersionHeader | OperationResponseControlRequestV1)

async apply(request)[source]

Consume one exact APPLY response through the bound runtime authority.

Return type:

TypeAliasType

Parameters:

request (OperationResponseApplyRequestV1)

async reject(request)[source]

Consume one exact REJECT response through the bound runtime authority.

Return type:

TypeAliasType

Parameters:

request (OperationResponseRejectRequestV1)

class OperationCancellationService(reader, registry, supervisor)[source]

Bases: object

Request cooperative cancellation through one versioned public boundary.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
supervisor: OperationControlSupervisor
async request(request)[source]

Request cancellation or return a stable typed refusal.

Return type:

TypeAliasType

Parameters:

request (OperationCancellationVersionHeader | OperationCancellationRequestV1)

class OperationDetachService(reader, registry, supervisor)[source]

Bases: object

Detach a frontend from an operation through one public boundary.

Parameters:
reader: OperationObservationReader
registry: OperationRegistry
supervisor: OperationControlSupervisor
async detach(request)[source]

Detach the requested operation or return a stable typed refusal.

Return type:

TypeAliasType

Parameters:

request (OperationDetachVersionHeader | OperationDetachRequestV1)

class UnavailableSnapshot[source]

Bases: object

async read_snapshot(reader, operation_id)[source]
Return type:

OperationPersistedSnapshot | UnavailableSnapshot | None

Parameters: