cadrumo.application.operations.frontend_requests module

Renderer-neutral operation request, response, refusal, and event contracts.

class OperationObservationRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for operation observation requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
CURSOR_AHEAD
INVALID_CURSOR
DEFINITION_CONTRACT_MISMATCH
OBSERVATION_UNAVAILABLE
class OperationReviewProjectionRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for REVIEW projection requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
REVIEW_NOT_PENDING
STALE_REVIEW_REFERENCE
REVIEW_EXPIRED
DEFINITION_CONTRACT_MISMATCH
REVIEW_SCHEMA_MISMATCH
REVIEW_PROJECTION_UNAVAILABLE
class OperationResultProjectionRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for settled-result projection requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
OPERATION_NOT_TERMINAL
OPERATION_NOT_SUCCESSFUL
STALE_OPERATION_REVISION
DEFINITION_CONTRACT_MISMATCH
RESULT_SCHEMA_MISMATCH
RESULT_PROJECTION_UNAVAILABLE
class OperationWorkspaceRefreshTargetRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for workspace refresh-target requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
OPERATION_NOT_TERMINAL
OPERATION_NOT_SUCCESSFUL
REFRESH_ADAPTER_UNAVAILABLE
DEFINITION_CONTRACT_MISMATCH
REFRESH_SCHEMA_MISMATCH
UNSAFE_REFRESH_TARGET
class OperationResponseControlRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for response-control requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
RESPONSE_NOT_PENDING
STALE_OPERATION_REVISION
RESPONSE_AUTHORITY_UNAVAILABLE
class OperationCancellationRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for cancellation requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
STALE_OPERATION_REVISION
OPERATION_TERMINAL
CANCELLATION_UNSUPPORTED
CANCELLATION_UNAVAILABLE
class OperationDetachRefusalCode(*values)[source]

Bases: StrEnum

Stable refusal codes for detach requests.

UNSUPPORTED_VERSION
UNKNOWN_OPERATION
STALE_OPERATION_REVISION
DETACH_NOT_ALLOWED
class OperationObservationVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact observation request dispatch.

Parameters:

observation_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

observation_version: Annotated[int, Field(ge=1)]
class OperationReviewProjectionVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact REVIEW request dispatch.

Parameters:

review_projection_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

review_projection_version: Annotated[int, Field(ge=1)]
class OperationResponseControlVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact response-control request dispatch.

Parameters:

response_control_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

response_control_version: Annotated[int, Field(ge=1)]
class OperationCancellationVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact cancellation request dispatch.

Parameters:

cancellation_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

cancellation_version: Annotated[int, Field(ge=1)]
class OperationDetachVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact detach request dispatch.

Parameters:

detach_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

detach_version: Annotated[int, Field(ge=1)]
class OperationWorkspaceRefreshTargetVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact refresh-target request dispatch.

Parameters:

refresh_target_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

refresh_target_version: Annotated[int, Field(ge=1)]
class OperationResultProjectionVersionHeader(**data)[source]

Bases: BaseModel

Minimal header parsed before exact settled-result projection dispatch.

Parameters:

result_projection_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

result_projection_version: Annotated[int, Field(ge=1)]
class OperationObservationRequestV1(**data)[source]

Bases: BaseModel

Request one atomic projection and bounded event page.

Parameters:

  • observation_version (Literal[1])

  • operation_id (OperationId)

  • after_cursor (OperationEventCursor)

  • page_limit (OperationReplayLimit)

observation_version: Literal[1]
operation_id: OperationId
after_cursor: OperationEventCursor
page_limit: OperationReplayLimit
class OperationReviewProjectionRequestV1(**data)[source]

Bases: BaseModel

Versioned request for a safe REVIEW projection.

Parameters:
review_projection_version: Literal[1]
reference: OperationReviewProjectionReferenceV1
class OperationReviewProjectionSuccessV1(**data)[source]

Bases: BaseModel, Generic

Successful typed REVIEW projection response.

Parameters:
outcome: Literal['success']
review_projection_version: Literal[1]
projection_schema: OperationSchemaIdentityV1
definition_contract_digest: ContentDigest
projection: ReviewProjectionT
class OperationReviewProjectionRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a REVIEW projection request.

Parameters:
outcome: Literal['refused']
review_projection_version: Literal[1]
code: OperationReviewProjectionRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationResponseControlRequestV1(**data)[source]

Bases: BaseModel

Versioned request for the safe response-control surface.

Parameters:

  • response_control_version (Literal[1])

  • operation_id (OperationId)

  • interaction_id (OperationInteractionId)

  • revision (OperationRevision)

  • actor_ref (OperationActorReference)

response_control_version: Literal[1]
operation_id: OperationId
interaction_id: OperationInteractionId
revision: OperationRevision
actor_ref: OperationActorReference
class OperationResponseControlSuccessV1(**data)[source]

Bases: BaseModel

Successful response-control inspection result.

Parameters:

  • outcome (Literal['success'])

  • response_control_version (Literal[1])

  • operation_id (OperationId)

  • interaction_id (OperationInteractionId)

  • revision (OperationRevision)

  • available (bool)

  • permitted_intents (frozenset[Literal[OperationResponseIntent.APPLY, OperationResponseIntent.REJECT]])

outcome: Literal['success']
response_control_version: Literal[1]
operation_id: OperationId
interaction_id: OperationInteractionId
revision: OperationRevision
available: bool
permitted_intents: frozenset[OperationResponseIntentValue]
class OperationResponseControlRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a response-control request.

Parameters:
outcome: Literal['refused']
response_control_version: Literal[1]
code: OperationResponseControlRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationResponseApplyRequestV1(**data)[source]

Bases: OperationResponseControlRequestV1

Apply one exact pending REVIEW through separately held authority.

Parameters:

  • response_control_version (Literal[1])

  • operation_id (OperationId)

  • interaction_id (OperationInteractionId)

  • revision (OperationRevision)

  • actor_ref (OperationActorReference)

  • response_action (Literal['apply'])

  • responded_at (datetime)

response_action: Literal['apply']
responded_at: datetime
class OperationResponseRejectRequestV1(**data)[source]

Bases: OperationResponseControlRequestV1

Reject one exact pending REVIEW through separately held authority.

Parameters:

  • response_control_version (Literal[1])

  • operation_id (OperationId)

  • interaction_id (OperationInteractionId)

  • revision (OperationRevision)

  • actor_ref (OperationActorReference)

  • response_action (Literal['reject'])

  • responded_at (datetime)

  • reason_code (OperationEventCode | None)

response_action: Literal['reject']
responded_at: datetime
reason_code: OperationEventCode | None
class OperationResponseMutationSuccessV1(**data)[source]

Bases: BaseModel

Safe acknowledgement that one exact response was durably consumed.

Parameters:

  • outcome (Literal['success'])

  • response_control_version (Literal[1])

  • operation_id (OperationId)

  • interaction_id (OperationInteractionId)

  • revision (OperationRevision)

  • response_action (Literal[OperationResponseIntent.APPLY, OperationResponseIntent.REJECT])

outcome: Literal['success']
response_control_version: Literal[1]
operation_id: OperationId
interaction_id: OperationInteractionId
revision: OperationRevision
response_action: OperationResponseIntentValue
class OperationSubmissionReceiptV1(**data)[source]

Bases: BaseModel

Credential-free result of durable registered-operation submission.

Parameters:
submission_version: Literal[1]
operation_id: OperationId
secret_requirement: OperationSecretRequirement | None
class OperationCancellationRequestV1(**data)[source]

Bases: BaseModel

Versioned request to cooperatively cancel an operation.

Parameters:

  • cancellation_version (Literal[1])

  • operation_id (OperationId)

  • expected_revision (OperationRevision)

cancellation_version: Literal[1]
operation_id: OperationId
expected_revision: OperationRevision
class OperationCancellationSuccessV1(**data)[source]

Bases: BaseModel

Successful cooperative-cancellation request result.

Parameters:

  • outcome (Literal['success'])

  • cancellation_version (Literal[1])

  • operation_id (OperationId)

  • revision (OperationRevision)

  • cancellation_requested (Literal[True])

  • cancellation_acknowledged (bool)

outcome: Literal['success']
cancellation_version: Literal[1]
operation_id: OperationId
revision: OperationRevision
cancellation_requested: Literal[True]
cancellation_acknowledged: bool
class OperationCancellationRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a cancellation request.

Parameters:
outcome: Literal['refused']
cancellation_version: Literal[1]
code: OperationCancellationRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationDetachRequestV1(**data)[source]

Bases: BaseModel

Versioned request to detach an operation from a frontend.

Parameters:

  • detach_version (Literal[1])

  • operation_id (OperationId)

  • expected_revision (OperationRevision)

detach_version: Literal[1]
operation_id: OperationId
expected_revision: OperationRevision
class OperationDetachSuccessV1(**data)[source]

Bases: BaseModel

Successful frontend detach result.

Parameters:

  • outcome (Literal['success'])

  • detach_version (Literal[1])

  • operation_id (OperationId)

  • revision (OperationRevision)

  • detached (Literal[True])

outcome: Literal['success']
detach_version: Literal[1]
operation_id: OperationId
revision: OperationRevision
detached: Literal[True]
class OperationDetachRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a detach request.

Parameters:
outcome: Literal['refused']
detach_version: Literal[1]
code: OperationDetachRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationWorkspaceRefreshTargetRequestV1(**data)[source]

Bases: BaseModel

Resolve a restart-safe target without accepting a caller result reference.

Parameters:
refresh_target_version: Literal[1]
operation_id: OperationId
terminal_revision: OperationRevision
definition_contract_digest: ContentDigest
target_schema: OperationSchemaIdentityV1
class OperationWorkspaceRefreshTargetSuccessV1(**data)[source]

Bases: BaseModel, Generic

Successful typed workspace refresh target resolution.

Parameters:
outcome: Literal['success']
refresh_target_version: Literal[1]
target_schema: OperationSchemaIdentityV1
definition_contract_digest: ContentDigest
target: RefreshTargetT
class OperationWorkspaceRefreshTargetRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a workspace refresh-target request.

Parameters:
outcome: Literal['refused']
refresh_target_version: Literal[1]
code: OperationWorkspaceRefreshTargetRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationResultProjectionRequestV1(**data)[source]

Bases: BaseModel

Resolve a settled operation’s safe public result without a raw reference.

Symmetric with OperationWorkspaceRefreshTargetRequestV1: the caller never supplies the private result_ref itself, only the operation identity, the terminal revision it expects, the definition contract it trusts, and the registered result schema it wants back.

Parameters:
result_projection_version: Literal[1]
operation_id: OperationId
terminal_revision: OperationRevision
definition_contract_digest: ContentDigest
result_schema: OperationSchemaIdentityV1
class OperationResultProjectionSuccessV1(**data)[source]

Bases: BaseModel, Generic

Successful typed settled-result projection.

Parameters:
outcome: Literal['success']
result_projection_version: Literal[1]
result_schema: OperationSchemaIdentityV1
definition_contract_digest: ContentDigest
projection: ResultProjectionT
class OperationResultProjectionRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for a settled-result projection request.

Parameters:
outcome: Literal['refused']
result_projection_version: Literal[1]
code: OperationResultProjectionRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None
class OperationPublicPhaseEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one operation phase event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.PHASE])

  • phase_code (OperationEventCode)

kind: Literal[OperationEventKind.PHASE]
phase_code: OperationEventCode
class OperationPublicProgressEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one bounded operation progress event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.PROGRESS])

  • completed (Annotated[int, Ge(ge=0)])

  • total (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])])

  • unit_code (OperationEventCode | None)

kind: Literal[OperationEventKind.PROGRESS]
completed: NonNegativeInt
total: Annotated[int, Field(gt=0)]
unit_code: OperationEventCode | None
class OperationPublicLogEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one structured operation log event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.LOG])

  • severity (OperationLogSeverity)

  • diagnostic_ref (OperationDiagnosticReference | None)

kind: Literal[OperationEventKind.LOG]
severity: OperationLogSeverity
diagnostic_ref: OperationDiagnosticReference | None
class OperationPublicEffectEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one operation effect event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.EFFECT])

  • effect (OperationEffect)

kind: Literal[OperationEventKind.EFFECT]
effect: OperationEffect
class OperationPublicNoticeEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one localized-notice identity event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.NOTICE])

  • notice_code (OperationEventCode)

kind: Literal[OperationEventKind.NOTICE]
notice_code: OperationEventCode
class OperationPublicReconciliationEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one startup-reconciliation event.

Parameters:
kind: Literal[OperationEventKind.RECONCILIATION]
outcome: OperationReconciliationOutcome
class OperationPublicDiagnosticEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one redacted diagnostic-reference event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.DIAGNOSTIC])

  • diagnostic_ref (OperationDiagnosticReference)

kind: Literal[OperationEventKind.DIAGNOSTIC]
diagnostic_ref: OperationDiagnosticReference
class OperationPublicInteractionEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one interaction lifecycle event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.INTERACTION])

  • interaction_id (OperationInteractionId)

kind: Literal[OperationEventKind.INTERACTION]
interaction_id: OperationInteractionId
class OperationPublicTerminalEventV1(**data)[source]

Bases: _OperationPublicEventBase

Public projection of one terminal operation receipt event.

Parameters:

  • revision (OperationRevision)

  • sequence (OperationEventSequence)

  • timestamp (datetime)

  • code (OperationEventCode)

  • kind (Literal[OperationEventKind.TERMINAL])

  • condition (OperationTerminalCondition)

  • effect (OperationEffect)

  • result_ref (OperationReference | None)

  • refusal_ref (OperationReference | None)

  • failure_error_code (str | None)

  • diagnostic_ref (OperationDiagnosticReference | None)

kind: Literal[OperationEventKind.TERMINAL]
condition: OperationTerminalCondition
effect: OperationEffect
result_ref: OperationReference | None
refusal_ref: OperationReference | None
failure_error_code: str | None
diagnostic_ref: OperationDiagnosticReference | None
class OperationPublicEventPageV1(**data)[source]

Bases: BaseModel

Bounded public event replay page tied to one observation anchor.

Parameters:

  • observation_version (Literal[1])

  • operation_id (OperationId)

  • anchor_cursor (OperationEventCursor)

  • requested_cursor (OperationEventCursor)

  • status (PublicReplayStatus)

  • events (tuple[OperationPublicEventV1, ...])

  • next_cursor (OperationEventCursor)

  • restart_cursor (OperationEventCursor | None)

observation_version: Literal[1]
operation_id: OperationId
anchor_cursor: OperationEventCursor
requested_cursor: OperationEventCursor
status: PublicReplayStatus
events: tuple[OperationPublicEventV1, ...]
next_cursor: OperationEventCursor
restart_cursor: OperationEventCursor | None
class OperationObservationSuccessV1(**data)[source]

Bases: BaseModel

Successful atomic public operation observation.

Parameters:
outcome: Literal['success']
observation_version: Literal[1]
projection: OperationPublicProjectionV1
event_page: OperationPublicEventPageV1
class OperationObservationRefusalV1(**data)[source]

Bases: BaseModel

Renderer-neutral refusal for an operation observation request.

Parameters:
outcome: Literal['refused']
observation_version: Literal[1]
code: OperationObservationRefusalCode
requested_version: Annotated[int, Field(ge=1)] | None
supported_version: Literal[1]
diagnostic_ref: OperationDiagnosticReference | None