cayu.sessions.recovery

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`ContinuationRecoveryExpectation`

from cayu.sessions import ContinuationRecoveryExpectation

Exact consumed-ticket invocation selection, never a new execution grant.

Bases: ContractValue.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`session_instance_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`ticket_key`	`StrictStr`	`Field(pattern='^session-continuation:[0-9a-f]{64}$')`
`record_sha256`	`StrictStr`	`Field(pattern='^[0-9a-f]{64}$')`
`admission_command_digest`	`StrictStr`	`Field(pattern='^[0-9a-f]{64}$')`
`admission_expected_run_epoch`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`profile_digest`	`StrictStr`	`Field(pattern='^[0-9a-f]{64}$')`

bounded_input (method)

ContinuationRecoveryExpectation.bounded_input(value: object) -> Any

immutable_fields (method)

ContinuationRecoveryExpectation.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

`ProducerRecoveryExpectation`

from cayu.sessions import ProducerRecoveryExpectation

Exact native attachment selection, not execution or cleanup authority.

Bases: ContractValue.

Fields and attributes

Name	Type	Default
`session_instance_id`	`str`	`required`
`attachment_operation_key`	`str`	`required`
`attachment_commitment`	`str`	`required`

bounded_input (method)

ProducerRecoveryExpectation.bounded_input(value: object) -> Any

immutable_fields (method)

ProducerRecoveryExpectation.immutable_fields() -> ContractValue

validate_identity (method)

ProducerRecoveryExpectation.validate_identity(value: str, info) -> str

validate_commitment (method)

ProducerRecoveryExpectation.validate_commitment(value: str) -> str

Release source · Runtime guarantees · Capability guides

`RECOVERY_PLAN_MAX_CONCURRENCY`

from cayu.sessions import RECOVERY_PLAN_MAX_CONCURRENCY

RECOVERY_PLAN_MAX_CONCURRENCY = 32

Release source · Runtime guarantees · Capability guides

`RECOVERY_PLAN_MAX_INSPECTIONS`

from cayu.sessions import RECOVERY_PLAN_MAX_INSPECTIONS

RECOVERY_PLAN_MAX_INSPECTIONS = 10000

Release source · Runtime guarantees · Capability guides

`RECOVERY_PLAN_MAX_ITEMS`

from cayu.sessions import RECOVERY_PLAN_MAX_ITEMS

RECOVERY_PLAN_MAX_ITEMS = 1000

Release source · Runtime guarantees · Capability guides

`RECOVERY_PLAN_SCHEMA_VERSION`

from cayu.sessions import RECOVERY_PLAN_SCHEMA_VERSION

RECOVERY_PLAN_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`RecoveryBlockerCode`

from cayu.sessions import RecoveryBlockerCode

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`REGISTRATION_UNAVAILABLE`	`class attribute`	`'registration_unavailable'`
`REGISTRATION_INCOMPATIBLE`	`class attribute`	`'registration_incompatible'`
`ACTIVE_RECOVERY_CLAIM`	`class attribute`	`'active_recovery_claim'`
`ACTIVE_EXECUTION_OWNER`	`class attribute`	`'active_execution_owner'`
`ACTIVE_TASK_CLAIM`	`class attribute`	`'active_task_claim'`
`MODEL_EFFECT_OUTCOME_UNKNOWN`	`class attribute`	`'model_effect_outcome_unknown'`
`TOOL_EFFECT_OUTCOME_UNKNOWN`	`class attribute`	`'tool_effect_outcome_unknown'`
`TOOL_EFFECT_CONTINUATION_REQUIRED`	`class attribute`	`'tool_effect_continuation_required'`
`TOOL_APPROVAL_REQUIRED`	`class attribute`	`'tool_approval_required'`
`USER_INPUT_REQUIRED`	`class attribute`	`'user_input_required'`
`INVALID_DURABLE_STATE`	`class attribute`	`'invalid_durable_state'`

Release source · Runtime guarantees · Capability guides

`RecoveryClaimEvidence`

from cayu.sessions import RecoveryClaimEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`claim_ref`	`str`	`required`
`lease_expires_at`	`datetime`	`required`

validate_claim_ref (method)

RecoveryClaimEvidence.validate_claim_ref(value: str) -> str

normalize_lease (method)

RecoveryClaimEvidence.normalize_lease(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

`RecoveryDecision`

from cayu.sessions import RecoveryDecision

One operator-selected action, bound to an exact plan item.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`item_id`	`str`	`required`
`action`	`RecoveryPlanAction`	`required`
`message`	`str \| None`	`Field(default=None, max_length=4096)`

validate_item_id (method)

RecoveryDecision.validate_item_id(value: str) -> str

validate_message (method)

RecoveryDecision.validate_message(value: str | None) -> str | None

require_tool_evidence_message (method)

RecoveryDecision.require_tool_evidence_message() -> Self

Release source · Runtime guarantees · Capability guides

`RecoveryEnvironmentEvidence`

from cayu.sessions import RecoveryEnvironmentEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`allocation_states`	`tuple[EnvironmentAllocationState, ...]`	`Field(default=(), max_length=64)`
`completion_finalization_pending`	`StrictBool`	`False`
`finalization_outcome`	`Literal['completed', 'failed', 'interrupted'] \| None`	`None`

Release source · Runtime guarantees · Capability guides

`RecoveryExecutionRequest`

from cayu.sessions import RecoveryExecutionRequest

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`plan`	`RecoveryPlan`	`required`
`execution_id`	`str`	`required`
`decisions`	`tuple[RecoveryDecision, ...]`	`Field(default=(), max_length=RECOVERY_PLAN_MAX_ITEMS)`
`max_concurrency`	`StrictInt`	`Field(default=1, ge=1, le=RECOVERY_PLAN_MAX_CONCURRENCY)`

validate_execution_id (method)

RecoveryExecutionRequest.validate_execution_id(value: str) -> str

validate_decisions (method)

RecoveryExecutionRequest.validate_decisions() -> Self

Release source · Runtime guarantees · Capability guides

`RecoveryInterruptionCascadeEvidence`

from cayu.sessions import RecoveryInterruptionCascadeEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt_ref`	`str`	`required`
`generation`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`claim_ref`	`str \| None`	`None`
`lease_expires_at`	`datetime \| None`	`None`
`failure_recorded`	`StrictBool`	`False`

validate_refs (method)

RecoveryInterruptionCascadeEvidence.validate_refs(value: str | None, info) -> str | None

normalize_lease (method)

RecoveryInterruptionCascadeEvidence.normalize_lease(value: datetime | None) -> datetime | None

Release source · Runtime guarantees · Capability guides

`RecoveryItemExecutionStatus`

from cayu.sessions import RecoveryItemExecutionStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`EXECUTED`	`class attribute`	`'executed'`
`LEFT_INTACT`	`class attribute`	`'left_intact'`
`BLOCKED`	`class attribute`	`'blocked'`
`FAILED`	`class attribute`	`'failed'`

Release source · Runtime guarantees · Capability guides

`RecoveryItemReceipt`

from cayu.sessions import RecoveryItemReceipt

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`plan_id`	`str`	`required`
`item_id`	`str`	`required`
`execution_id`	`str`	`required`
`session_id`	`str`	`required`
`action`	`RecoveryPlanAction`	`required`
`status`	`RecoveryItemExecutionStatus`	`required`
`final_session_status`	`SessionStatus`	`required`
`final_run_epoch`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`recovery_actions`	`tuple[IncompleteSessionRecoveryAction, ...]`	`()`
`event_ids`	`tuple[str, ...]`	`Field(default=(), max_length=256)`
`receipt_event_id`	`str \| None`	`None`
`replayed`	`StrictBool`	`False`
`error_code`	`str \| None`	`None`

validate_ids (method)

RecoveryItemReceipt.validate_ids(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryModelStageEvidence`

from cayu.sessions import RecoveryModelStageEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`stage_ref`	`str`	`required`
`state`	`Literal['in_flight', 'completed']`	`required`
`dispatched`	`StrictBool`	`required`
`provider_reattachment_supported`	`StrictBool`	`required`
`provider_operation_ref`	`str \| None`	`None`
`local_http_cleanup`	`Literal['unknown', 'succeeded', 'failed']`	`'unknown'`
`reservation_count`	`StrictInt`	`Field(ge=0, le=32)`

validate_refs (method)

RecoveryModelStageEvidence.validate_refs(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryPendingActionEvidence`

from cayu.sessions import RecoveryPendingActionEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`action_ref`	`str`	`required`
`kind`	`PendingActionKind`	`required`
`tool_name`	`str \| None`	`None`
`round_ref`	`str \| None`	`None`
`tool_call_ref`	`str \| None`	`None`

validate_refs (method)

RecoveryPendingActionEvidence.validate_refs(value: str | None, info) -> str | None

validate_tool_name (method)

RecoveryPendingActionEvidence.validate_tool_name(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryPlan`

from cayu.sessions import RecoveryPlan

One immutable, content-addressed read-only recovery plan page.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.recovery-plan']`	`'cayu.recovery-plan'`
`schema_version`	`Literal[1]`	`RECOVERY_PLAN_SCHEMA_VERSION`
`plan_id`	`str`	`required`
`created_at`	`datetime`	`required`
`request`	`RecoveryPlanRequest`	`required`
`items`	`tuple[RecoveryPlanItem, ...]`	`Field(default=(), max_length=RECOVERY_PLAN_MAX_ITEMS)`
`inspected_session_count`	`StrictInt`	`Field(ge=0, le=RECOVERY_PLAN_MAX_INSPECTIONS)`
`next_cursor`	`str \| None`	`None`

validate_plan_id (method)

RecoveryPlan.validate_plan_id(value: str) -> str

normalize_created_at (method)

RecoveryPlan.normalize_created_at(value: datetime) -> datetime

validate_next_cursor (method)

RecoveryPlan.validate_next_cursor(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryPlanAction`

from cayu.sessions import RecoveryPlanAction

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`TERMINALIZE_ZERO_WORK`	`class attribute`	`'terminalize_zero_work'`
`AUTOMATIC_REPAIR`	`class attribute`	`'automatic_repair'`
`LEAVE_INTACT`	`class attribute`	`'leave_intact'`
`MODEL_MARK_FAILED`	`class attribute`	`'model_mark_failed'`
`MODEL_MARK_INTERRUPTED`	`class attribute`	`'model_mark_interrupted'`
`TOOL_MARK_COMPLETED`	`class attribute`	`'tool_mark_completed'`
`TOOL_MARK_FAILED`	`class attribute`	`'tool_mark_failed'`

Release source · Runtime guarantees · Capability guides

`RecoveryPlanBlocker`

from cayu.sessions import RecoveryPlanBlocker

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`code`	`RecoveryBlockerCode`	`required`
`action_ref`	`str \| None`	`None`

validate_action_ref (method)

RecoveryPlanBlocker.validate_action_ref(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryPlanBounds`

from cayu.sessions import RecoveryPlanBounds

Hard read and result bounds for one recovery plan page.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`item_limit`	`StrictInt`	`Field(default=100, ge=1, le=RECOVERY_PLAN_MAX_ITEMS)`
`inspection_limit`	`StrictInt`	`Field(default=1000, ge=1, le=RECOVERY_PLAN_MAX_INSPECTIONS)`

Release source · Runtime guarantees · Capability guides

`RecoveryPlanExecutionEvidence`

from cayu.sessions import RecoveryPlanExecutionEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`plan_ref`	`str`	`required`
`item_ref`	`str`	`required`
`execution_ref`	`str`	`required`
`decision_ref`	`str`	`required`
`lease_expires_at`	`datetime`	`required`

validate_refs (method)

RecoveryPlanExecutionEvidence.validate_refs(value: str, info) -> str

normalize_lease (method)

RecoveryPlanExecutionEvidence.normalize_lease(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

`RecoveryPlanExecutionFenced`

from cayu.sessions import RecoveryPlanExecutionFenced

Another live owner holds the per-session plan execution slot.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`RecoveryPlanItem`

from cayu.sessions import RecoveryPlanItem

One secret-free snapshot whose exact state gates later mutation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`item_id`	`str`	`required`
`state_fingerprint`	`str`	`required`
`authority_fingerprint`	`str`	`required`
`session_id`	`str`	`required`
`agent_name`	`str`	`required`
`provider_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`status`	`SessionStatus`	`required`
`run_epoch`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`execution_profile_fingerprint`	`str \| None`	`None`
`registration`	`RecoveryRegistrationEvidence`	`required`
`recovery_claim`	`RecoveryClaimEvidence \| None`	`None`
`plan_execution`	`RecoveryPlanExecutionEvidence \| None`	`None`
`run_fence_ref`	`str`	`required`
`run_operation_ref`	`str \| None`	`None`
`task_claims`	`tuple[RecoveryTaskClaimEvidence, ...]`	`Field(default=(), max_length=1000)`
`pending_actions`	`tuple[RecoveryPendingActionEvidence, ...]`	`Field(default=(), max_length=200)`
`active_model_stage`	`RecoveryModelStageEvidence \| None`	`None`
`environment_recovery`	`RecoveryEnvironmentEvidence`	`required`
`interruption_cascade`	`RecoveryInterruptionCascadeEvidence \| None`	`None`
`blockers`	`tuple[RecoveryPlanBlocker, ...]`	`Field(default=(), max_length=256)`
`allowed_actions`	`tuple[RecoveryPlanAction, ...]`	`Field(min_length=1, max_length=8)`

validate_ids (method)

RecoveryPlanItem.validate_ids(value: str, info) -> str

validate_optional_ids (method)

RecoveryPlanItem.validate_optional_ids(value: str | None, info) -> str | None

validate_fingerprints (method)

RecoveryPlanItem.validate_fingerprints(value: str | None, info) -> str | None

validate_actions (method)

RecoveryPlanItem.validate_actions() -> Self

Release source · Runtime guarantees · Capability guides

`RecoveryPlanRequest`

from cayu.sessions import RecoveryPlanRequest

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`selection`	`RecoveryPlanSelection`	`required`
`bounds`	`RecoveryPlanBounds`	`Field(default_factory=RecoveryPlanBounds)`
`producer`	`ProducerRecoveryExpectation \| None`	`None`
`continuation`	`ContinuationRecoveryExpectation \| None`	`None`
`participant_context`	`CollaborationAccessContext \| None`	`None`

validate_producer_selection (method)

RecoveryPlanRequest.validate_producer_selection() -> Self

Release source · Runtime guarantees · Capability guides

`RecoveryPlanSelection`

from cayu.sessions import RecoveryPlanSelection

Explicit, bounded selection of durable sessions to inspect.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_ids`	`tuple[str, ...]`	`Field(default=(), max_length=RECOVERY_PLAN_MAX_ITEMS)`
`statuses`	`frozenset[SessionStatus]`	`frozenset()`
`inactive_for_seconds`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`cursor`	`str \| None`	`None`

validate_session_ids (method)

RecoveryPlanSelection.validate_session_ids(value: object) -> tuple[str, ...]

validate_statuses (method)

RecoveryPlanSelection.validate_statuses(value: object) -> frozenset[SessionStatus]

validate_cursor (method)

RecoveryPlanSelection.validate_cursor(value: str | None) -> str | None

validate_selection (method)

RecoveryPlanSelection.validate_selection() -> Self

Release source · Runtime guarantees · Capability guides

`RecoveryReceipt`

from cayu.sessions import RecoveryReceipt

Bounded aggregate of per-session durable recovery receipts.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.recovery-receipt']`	`'cayu.recovery-receipt'`
`schema_version`	`Literal[1]`	`RECOVERY_PLAN_SCHEMA_VERSION`
`plan_id`	`str`	`required`
`execution_id`	`str`	`required`
`items`	`tuple[RecoveryItemReceipt, ...]`	`Field(max_length=RECOVERY_PLAN_MAX_ITEMS)`

validate_ids (method)

RecoveryReceipt.validate_ids(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`RecoveryRegistrationEvidence`

from cayu.sessions import RecoveryRegistrationEvidence

Safe result of comparing durable execution authority with this app.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`status`	`RecoveryRegistrationStatus`	`required`
`expected_execution_profile_fingerprint`	`str \| None`	`None`
`validated_execution_profile_fingerprint`	`str \| None`	`None`
`reason_code`	`str \| None`	`None`

validate_fingerprint (method)

RecoveryRegistrationEvidence.validate_fingerprint(value: str | None, info) -> str | None

validate_reason_code (method)

RecoveryRegistrationEvidence.validate_reason_code(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`RecoveryRegistrationStatus`

from cayu.sessions import RecoveryRegistrationStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`TERMINALIZATION_ONLY`	`class attribute`	`'terminalization_only'`
`READY`	`class attribute`	`'ready'`
`MISSING_AGENT`	`class attribute`	`'missing_agent'`
`MISSING_PROVIDER`	`class attribute`	`'missing_provider'`
`MISSING_ENVIRONMENT`	`class attribute`	`'missing_environment'`
`INCOMPATIBLE`	`class attribute`	`'incompatible'`

Release source · Runtime guarantees · Capability guides

`RecoveryTaskClaimEvidence`

from cayu.sessions import RecoveryTaskClaimEvidence

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`task_ref`	`str`	`required`
`status`	`TaskStatus`	`required`
`ownership_status`	`Literal['active', 'expired', 'unowned', 'direct', 'invalid']`	`'active'`
`worker_ref`	`str \| None`	`None`
`lease_expires_at`	`datetime \| None`	`None`

validate_refs (method)

RecoveryTaskClaimEvidence.validate_refs(value: str | None, info) -> str | None

normalize_lease (method)

RecoveryTaskClaimEvidence.normalize_lease(value: datetime | None) -> datetime | None

Release source · Runtime guarantees · Capability guides

`StaleRecoveryPlanError`

from cayu.sessions import StaleRecoveryPlanError

The durable state no longer matches the supplied plan item.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`StartupRecoveryBlockedSession`

from cayu.sessions import StartupRecoveryBlockedSession

Bounded operator evidence; contains no checkpoint or exception content.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`blocker_codes`	`tuple[RecoveryBlockerCode, ...]`	`Field(min_length=1, max_length=16)`

validate_session_id (method)

StartupRecoveryBlockedSession.validate_session_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

`StartupRecoveryResult`

from cayu.sessions import StartupRecoveryResult

Latest process-local interruption sweep, retaining at most 100 blocked roots.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`1`
`completed`	`StrictBool`	`False`
`status`	`Literal['not_started', 'running', 'completed', 'failed']`	`'not_started'`
`sweep_count`	`StrictInt`	`Field(default=0, ge=0)`
`scheduled_roots`	`StrictInt`	`Field(default=0, ge=0)`
`deferred_session_count`	`StrictInt`	`Field(default=0, ge=0)`
`skipped_session_count`	`StrictInt`	`Field(default=0, ge=0)`
`blocked_session_count`	`StrictInt`	`Field(default=0, ge=0)`
`blocked_sessions`	`tuple[StartupRecoveryBlockedSession, ...]`	`Field(default=(), max_length=100)`
`blocked_sessions_truncated`	`StrictBool`	`False`

Release source · Runtime guarantees · Capability guides