cayu.runtime.local_execution_attempts

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.

`build_local_execution_attempt_authority`

from cayu import build_local_execution_attempt_authority

build_local_execution_attempt_authority(*, app: CayuApp, task: Task, worker_id: str, request: LocalExecutionAttemptRequest, attempt_id: str | None=None) -> LocalExecutionAttemptAuthority

Release source · Runtime guarantees · Capability guides

`local_execution_attempt_capability_evidence`

from cayu import local_execution_attempt_capability_evidence

local_execution_attempt_capability_evidence(lifetime: LocalExecutionAttemptLifetime) -> CapabilityEvidence

Release source · Runtime guarantees · Capability guides

`LOCAL_EXECUTION_ATTEMPT_SCHEMA_VERSION`

from cayu import LOCAL_EXECUTION_ATTEMPT_SCHEMA_VERSION

LOCAL_EXECUTION_ATTEMPT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`local_execution_parent_death_containment_platform_candidate`

from cayu import local_execution_parent_death_containment_platform_candidate

local_execution_parent_death_containment_platform_candidate() -> bool

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptAuthority`

from cayu import LocalExecutionAttemptAuthority

Bases: BaseModel.

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
`schema_version`	`Literal[1]`	`LOCAL_EXECUTION_ATTEMPT_SCHEMA_VERSION`
`attempt_id`	`str`	`required`
`task_id`	`str`	`required`
`task_created_at`	`datetime`	`required`
`task_claim_updated_at`	`datetime`	`required`
`task_claim_lease_expires_at`	`datetime`	`required`
`task_invocation_sha256`	`str`	`required`
`worker_id`	`str`	`required`
`retry_series_id`	`str \| None`	`None`
`retry_attempt`	`StrictInt \| None`	`Field(default=None, ge=1, le=100)`
`session_id`	`str \| None`	`None`
`session_instance_id`	`str \| None`	`None`
`effect_lineage_id`	`str`	`required`
`command_sha256`	`str`	`required`
`execution_profile_fingerprint`	`str \| None`	`None`
`workspace_identity`	`str \| None`	`None`
`lifetime`	`LocalExecutionAttemptLifetime`	`required`
`effect_policy`	`LocalExecutionEffectPolicy`	`required`
`idempotency_key_sha256`	`str \| None`	`None`
`containment_backend`	`str`	`required`
`request_sha256`	`str`	`required`

validate_required_identity (method)

LocalExecutionAttemptAuthority.validate_required_identity(value: str, info) -> str

validate_optional_authority_identity (method)

LocalExecutionAttemptAuthority.validate_optional_authority_identity(value: str | None, info) -> str | None

validate_authority_digest (method)

LocalExecutionAttemptAuthority.validate_authority_digest(value: str | None, info) -> str | None

normalize_task_authority_datetime (method)

LocalExecutionAttemptAuthority.normalize_task_authority_datetime(value: datetime, info) -> datetime

validate_task_claim_window (method)

LocalExecutionAttemptAuthority.validate_task_claim_window() -> LocalExecutionAttemptAuthority

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptConflict`

from cayu import LocalExecutionAttemptConflict

An exact local execution-attempt identity conflicts with durable state.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptCoordinator`

from cayu import LocalExecutionAttemptCoordinator

Task-backed owner for one complete local process-tree attempt.

init (method)

LocalExecutionAttemptCoordinator.__init__(task_store: TaskStore, *, state_dir: str | os.PathLike[str] | None=None) -> None

state_dir (property)

LocalExecutionAttemptCoordinator.state_dir() -> Path

capability_evidence (property)

LocalExecutionAttemptCoordinator.capability_evidence() -> CapabilityEvidence

run (method)

async LocalExecutionAttemptCoordinator.run(*, app: CayuApp, task: Task, worker_id: str, request: LocalExecutionAttemptRequest) -> LocalExecutionAttemptResult

recover (method)

async LocalExecutionAttemptCoordinator.recover(*, worker_id: str, limit: int=32) -> tuple[LocalExecutionAttemptRecord, ...]

drain (method)

async LocalExecutionAttemptCoordinator.drain(*, timeout_seconds: float=5.0) -> tuple[LocalExecutionAttemptRecord, ...]

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptEffectOutcome`

from cayu import LocalExecutionAttemptEffectOutcome

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`NOT_STARTED`	`class attribute`	`'not_started'`
`SUCCEEDED`	`class attribute`	`'succeeded'`
`FAILED`	`class attribute`	`'failed'`
`OUTCOME_UNKNOWN`	`class attribute`	`'outcome_unknown'`

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptLifetime`

from cayu import LocalExecutionAttemptLifetime

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`PARENT_DEATH_CONTAINMENT`	`class attribute`	`'parent_death_containment'`
`GRACEFUL_CLEANUP`	`class attribute`	`'graceful_cleanup'`
`PERSISTENT_DETACHED`	`class attribute`	`'persistent_detached'`

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptLimits`

from cayu import LocalExecutionAttemptLimits

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`deadline_seconds`	`float \| None`	`Field(default=None, gt=0, le=31536000)`
`startup_timeout_seconds`	`float`	`Field(default=DEFAULT_LOCAL_EXECUTION_STARTUP_TIMEOUT_SECONDS, gt=0, le=300)`
`term_grace_seconds`	`float`	`Field(default=DEFAULT_LOCAL_EXECUTION_TERM_GRACE_SECONDS, gt=0, le=300)`
`kill_grace_seconds`	`float`	`Field(default=DEFAULT_LOCAL_EXECUTION_KILL_GRACE_SECONDS, gt=0, le=300)`
`max_output_bytes`	`StrictInt`	`Field(default=DEFAULT_LOCAL_EXECUTION_MAX_OUTPUT_BYTES, ge=0, le=MAX_LOCAL_EXECUTION_OUTPUT_BYTES)`

validate_seconds_type (method)

LocalExecutionAttemptLimits.validate_seconds_type(value: object, info) -> object

validate_finite_seconds (method)

LocalExecutionAttemptLimits.validate_finite_seconds(value: float | None, info) -> float | None

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptListCursor`

from cayu import LocalExecutionAttemptListCursor

Stable keyset cursor for bounded unsettled-attempt discovery.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`created_at`	`datetime`	`required`
`attempt_id`	`str`	`required`

normalize_created_at (method)

LocalExecutionAttemptListCursor.normalize_created_at(value: datetime) -> datetime

validate_attempt_id (method)

LocalExecutionAttemptListCursor.validate_attempt_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptPhase`

from cayu import LocalExecutionAttemptPhase

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`PREPARED`	`class attribute`	`'prepared'`
`STARTING`	`class attribute`	`'starting'`
`RUNNING`	`class attribute`	`'running'`
`TERMINAL`	`class attribute`	`'terminal'`

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptQuiescence`

from cayu import LocalExecutionAttemptQuiescence

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`NOT_DISPATCHED`	`class attribute`	`'not_dispatched'`
`TERMINAL_NOT_QUIESCENT`	`class attribute`	`'terminal_not_quiescent'`
`QUIESCENT`	`class attribute`	`'quiescent'`
`UNAVAILABLE`	`class attribute`	`'unavailable'`
`PERSISTENT_DETACHED`	`class attribute`	`'persistent_detached'`

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptReceipt`

from cayu import LocalExecutionAttemptReceipt

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt_id`	`str`	`required`
`request_sha256`	`str`	`required`
`host_identity`	`str`	`required`
`boot_id`	`str`	`required`
`supervisor_nonce`	`str`	`required`
`root`	`LocalExecutionProcessIdentity \| None`	`None`
`terminal_reason`	`str`	`required`
`exit_code`	`StrictInt \| None`	`None`
`term_sent`	`StrictBool`	`False`
`kill_sent`	`StrictBool`	`False`
`descendants_observed`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`quiescence`	`LocalExecutionAttemptQuiescence`	`required`
`effect_outcome`	`LocalExecutionAttemptEffectOutcome`	`required`
`settled_at`	`datetime`	`required`
`receipt_sha256`	`str`	`required`

validate_receipt_identity (method)

LocalExecutionAttemptReceipt.validate_receipt_identity(value: str, info) -> str

validate_receipt_digest (method)

LocalExecutionAttemptReceipt.validate_receipt_digest(value: str, info) -> str

normalize_settled_at (method)

LocalExecutionAttemptReceipt.normalize_settled_at(value: datetime) -> datetime

validate_receipt_state (method)

LocalExecutionAttemptReceipt.validate_receipt_state() -> LocalExecutionAttemptReceipt

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptRecord`

from cayu import LocalExecutionAttemptRecord

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`authority`	`LocalExecutionAttemptAuthority`	`required`
`phase`	`LocalExecutionAttemptPhase`	`required`
`quiescence`	`LocalExecutionAttemptQuiescence`	`required`
`effect_outcome`	`LocalExecutionAttemptEffectOutcome`	`required`
`start`	`LocalExecutionAttemptStart \| None`	`None`
`receipt`	`LocalExecutionAttemptReceipt \| None`	`None`
`recovery_owner_id`	`str \| None`	`None`
`recovery_owner_expires_at`	`datetime \| None`	`None`
`recovery_generation`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`created_at`	`datetime`	`required`
`updated_at`	`datetime`	`required`

validate_recovery_owner_id (method)

LocalExecutionAttemptRecord.validate_recovery_owner_id(value: str | None) -> str | None

normalize_timestamps (method)

LocalExecutionAttemptRecord.normalize_timestamps(value: datetime | None, info) -> datetime | None

validate_lifecycle_state (method)

LocalExecutionAttemptRecord.validate_lifecycle_state() -> LocalExecutionAttemptRecord

retry_admissible (property)

LocalExecutionAttemptRecord.retry_admissible() -> bool

containment_settled (property)

LocalExecutionAttemptRecord.containment_settled() -> bool

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptRecoveryClaim`

from cayu import LocalExecutionAttemptRecoveryClaim

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt_id`	`str`	`required`
`request_sha256`	`str`	`required`
`recovery_owner_id`	`str`	`required`
`expected_recovery_generation`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`lease_seconds`	`StrictInt`	`Field(default=30, ge=1, le=300)`

validate_claim_identity (method)

LocalExecutionAttemptRecoveryClaim.validate_claim_identity(value: str, info) -> str

validate_claim_digest (method)

LocalExecutionAttemptRecoveryClaim.validate_claim_digest(value: str) -> str

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptRequest`

from cayu import LocalExecutionAttemptRequest

Ephemeral launch input; environment values are never durably persisted.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`effect_lineage_id`	`str`	`required`
`argv`	`tuple[str, ...]`	`Field(min_length=1, max_length=MAX_LOCAL_EXECUTION_COMMAND_ITEMS)`
`cwd`	`str \| None`	`None`
`env`	`dict[str, str]`	`Field(default_factory=dict)`
`inherit_env`	`StrictBool`	`False`
`lifetime`	`LocalExecutionAttemptLifetime`	`LocalExecutionAttemptLifetime.PARENT_DEATH_CONTAINMENT`
`effect_policy`	`LocalExecutionEffectPolicy`	`LocalExecutionEffectPolicy.NON_IDEMPOTENT_EXTERNAL`
`idempotency_key`	`str \| None`	`None`
`workspace_identity`	`str \| None`	`None`
`execution_profile_fingerprint`	`str \| None`	`None`
`limits`	`LocalExecutionAttemptLimits`	`Field(default_factory=LocalExecutionAttemptLimits)`

validate_effect_lineage_id (method)

LocalExecutionAttemptRequest.validate_effect_lineage_id(value: str) -> str

validate_optional_identity (method)

LocalExecutionAttemptRequest.validate_optional_identity(value: str | None, info) -> str | None

validate_argv (method)

LocalExecutionAttemptRequest.validate_argv(value: tuple[str, ...]) -> tuple[str, ...]

validate_cwd (method)

LocalExecutionAttemptRequest.validate_cwd(value: str | None) -> str | None

validate_env (method)

LocalExecutionAttemptRequest.validate_env(value: dict[str, str]) -> dict[str, str]

validate_effect_policy (method)

LocalExecutionAttemptRequest.validate_effect_policy() -> LocalExecutionAttemptRequest

effective_environment (method)

LocalExecutionAttemptRequest.effective_environment() -> dict[str, str]

durable_configuration (method)

LocalExecutionAttemptRequest.durable_configuration() -> dict[str, Any]

Return the secret-free fields that define retry/replacement authority.

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptResult`

from cayu import LocalExecutionAttemptResult

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt`	`LocalExecutionAttemptRecord`	`required`
`stdout`	`str`	`''`
`stderr`	`str`	`''`
`stdout_truncated`	`StrictBool`	`False`
`stderr_truncated`	`StrictBool`	`False`

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptSettlement`

from cayu import LocalExecutionAttemptSettlement

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt_id`	`str`	`required`
`request_sha256`	`str`	`required`
`receipt`	`LocalExecutionAttemptReceipt`	`required`
`recovery_owner_id`	`str \| None`	`None`
`expected_recovery_generation`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_DURABLE_JSON_INTEGER)`

validate_settlement_identity (method)

LocalExecutionAttemptSettlement.validate_settlement_identity(value: str, info) -> str

validate_settlement_digest (method)

LocalExecutionAttemptSettlement.validate_settlement_digest(value: str) -> str

validate_settlement_owner (method)

LocalExecutionAttemptSettlement.validate_settlement_owner(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptStart`

from cayu import LocalExecutionAttemptStart

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`attempt_id`	`str`	`required`
`request_sha256`	`str`	`required`
`host_identity`	`str`	`required`
`boot_id`	`str`	`required`
`supervisor_nonce`	`str`	`required`
`rendezvous_identity`	`str`	`required`
`supervisor`	`LocalExecutionProcessIdentity`	`required`
`root`	`LocalExecutionProcessIdentity \| None`	`None`
`started_at`	`datetime`	`required`

validate_start_identity (method)

LocalExecutionAttemptStart.validate_start_identity(value: str, info) -> str

validate_start_digest (method)

LocalExecutionAttemptStart.validate_start_digest(value: str) -> str

normalize_started_at (method)

LocalExecutionAttemptStart.normalize_started_at(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptUnavailable`

from cayu import LocalExecutionAttemptUnavailable

The requested local execution containment strength is unavailable.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

`LocalExecutionAttemptUnsettled`

from cayu import LocalExecutionAttemptUnsettled

A prior execution tree has not produced positive quiescence evidence.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

`LocalExecutionEffectPolicy`

from cayu import LocalExecutionEffectPolicy

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`LOCAL_ONLY`	`class attribute`	`'local_only'`
`IDEMPOTENT_EXTERNAL`	`class attribute`	`'idempotent_external'`
`NON_IDEMPOTENT_EXTERNAL`	`class attribute`	`'non_idempotent_external'`

Release source · Runtime guarantees · Capability guides

`LocalExecutionProcessIdentity`

from cayu import LocalExecutionProcessIdentity

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`pid`	`StrictInt`	`Field(gt=0, le=MAX_DURABLE_JSON_INTEGER)`
`process_group`	`StrictInt`	`Field(gt=0, le=MAX_DURABLE_JSON_INTEGER)`
`start_tick`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`proc_inode`	`StrictInt`	`Field(gt=0, le=MAX_DURABLE_JSON_INTEGER)`

Release source · Runtime guarantees · Capability guides