cayu.environments.lifecycle

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.

`copy_environment_lifecycle_policy`

from cayu.environments import copy_environment_lifecycle_policy

copy_environment_lifecycle_policy(policy: EnvironmentLifecyclePolicy | None) -> EnvironmentLifecyclePolicy | None

Release source · Runtime guarantees · Capability guides

`current_environment_lifecycle_progress_reporter`

from cayu.environments import current_environment_lifecycle_progress_reporter

Return the current runtime reporter without exposing session-owned internals.

current_environment_lifecycle_progress_reporter() -> EnvironmentLifecycleProgressReporter | None

Release source · Runtime guarantees · Capability guides

`DEFAULT_ENVIRONMENT_LIFECYCLE_TIMEOUT_SECONDS`

from cayu.environments import DEFAULT_ENVIRONMENT_LIFECYCLE_TIMEOUT_SECONDS

DEFAULT_ENVIRONMENT_LIFECYCLE_TIMEOUT_SECONDS = 3600.0

Release source · Runtime guarantees · Capability guides

`DEFAULT_ENVIRONMENT_PHASE_TIMEOUT_SECONDS`

from cayu.environments import DEFAULT_ENVIRONMENT_PHASE_TIMEOUT_SECONDS

DEFAULT_ENVIRONMENT_PHASE_TIMEOUT_SECONDS = 900.0

Release source · Runtime guarantees · Capability guides

`DEFAULT_ENVIRONMENT_PROGRESS_MIN_INTERVAL_SECONDS`

from cayu.environments import DEFAULT_ENVIRONMENT_PROGRESS_MIN_INTERVAL_SECONDS

DEFAULT_ENVIRONMENT_PROGRESS_MIN_INTERVAL_SECONDS = 0.25

Release source · Runtime guarantees · Capability guides

`DEFAULT_MAX_ENVIRONMENT_PROGRESS_EVENTS`

from cayu.environments import DEFAULT_MAX_ENVIRONMENT_PROGRESS_EVENTS

DEFAULT_MAX_ENVIRONMENT_PROGRESS_EVENTS = 128

Release source · Runtime guarantees · Capability guides

`environment_lifecycle_progress_from_event`

from cayu.environments import environment_lifecycle_progress_from_event

Validate one runtime lifecycle event as the public typed projection.

environment_lifecycle_progress_from_event(event: Event) -> EnvironmentLifecycleProgress

Release source · Runtime guarantees · Capability guides

`ENVIRONMENT_LIFECYCLE_PROGRESS_SCHEMA_VERSION`

from cayu.environments import ENVIRONMENT_LIFECYCLE_PROGRESS_SCHEMA_VERSION

ENVIRONMENT_LIFECYCLE_PROGRESS_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`environment_lifecycle_transition_from_event`

from cayu.environments import environment_lifecycle_transition_from_event

Validate one durable lifecycle transition event.

environment_lifecycle_transition_from_event(event: Event) -> EnvironmentLifecycleTransition

Release source · Runtime guarantees · Capability guides

`ENVIRONMENT_LIFECYCLE_TRANSITION_SCHEMA_VERSION`

from cayu.environments import ENVIRONMENT_LIFECYCLE_TRANSITION_SCHEMA_VERSION

ENVIRONMENT_LIFECYCLE_TRANSITION_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleDeadlineExceeded`

from cayu.environments import EnvironmentLifecycleDeadlineExceeded

A configured lifecycle or phase deadline elapsed at a safe progress boundary.

Bases: TimeoutError.

init (method)

EnvironmentLifecycleDeadlineExceeded.__init__(*, operation_id: str, phase: EnvironmentLifecyclePhase, scope: Literal['lifecycle', 'phase']) -> None

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleOperation`

from cayu.environments import EnvironmentLifecycleOperation

One runtime-owned unit of environment lifecycle work.

Bases: StrEnum.

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
`FACTORY`	`class attribute`	`'factory'`
`BINDING`	`class attribute`	`'binding'`
`FINALIZATION`	`class attribute`	`'finalization'`
`RELEASE`	`class attribute`	`'release'`
`RETAINED_CLEANUP`	`class attribute`	`'retained_cleanup'`

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecyclePhase`

from cayu.environments import EnvironmentLifecyclePhase

Content-free phases shared by factories, bindings, and cleanup.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`OWNERSHIP_ADMISSION`	`class attribute`	`'ownership_admission'`
`FACTORY_PROVISIONING`	`class attribute`	`'factory_provisioning'`
`FACTORY_RECONNECT`	`class attribute`	`'factory_reconnect'`
`SOURCE_OBSERVATION`	`class attribute`	`'source_observation'`
`STAGING_ADMISSION`	`class attribute`	`'staging_admission'`
`ARCHIVE_PREPARATION`	`class attribute`	`'archive_preparation'`
`TRANSFER`	`class attribute`	`'transfer'`
`TARGET_MATERIALIZATION`	`class attribute`	`'target_materialization'`
`EXECUTION_READY_PUBLICATION`	`class attribute`	`'execution_ready_publication'`
`FINAL_SOURCE_OBSERVATION`	`class attribute`	`'final_source_observation'`
`FINAL_TARGET_OBSERVATION`	`class attribute`	`'final_target_observation'`
`COPY_BACK_CONFLICT_PREFLIGHT`	`class attribute`	`'copy_back_conflict_preflight'`
`COPY_BACK_PUBLICATION`	`class attribute`	`'copy_back_publication'`
`ENVIRONMENT_RELEASE`	`class attribute`	`'environment_release'`
`RETAINED_CLEANUP`	`class attribute`	`'retained_cleanup'`

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecyclePolicy`

from cayu.environments import EnvironmentLifecyclePolicy

Finite lifecycle, phase, and progress-volume ceilings for one environment.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`lifecycle_timeout_seconds`	`StrictFloat`	`Field(default=DEFAULT_ENVIRONMENT_LIFECYCLE_TIMEOUT_SECONDS, gt=0, le=86400)`
`phase_timeout_seconds`	`Mapping[EnvironmentLifecyclePhase, StrictFloat]`	`Field(default_factory=_default_phase_timeouts)`
`progress_min_interval_seconds`	`StrictFloat`	`Field(default=DEFAULT_ENVIRONMENT_PROGRESS_MIN_INTERVAL_SECONDS, ge=0, le=60)`
`max_progress_events`	`StrictInt`	`Field(default=DEFAULT_MAX_ENVIRONMENT_PROGRESS_EVENTS, ge=32, le=MAX_ENVIRONMENT_PROGRESS_EVENTS)`

complete_phase_timeouts (method)

EnvironmentLifecyclePolicy.complete_phase_timeouts(value: object) -> object

freeze_phase_timeouts (method)

EnvironmentLifecyclePolicy.freeze_phase_timeouts(value: Mapping[EnvironmentLifecyclePhase, float]) -> Mapping[EnvironmentLifecyclePhase, float]

serialize_phase_timeouts (method)

EnvironmentLifecyclePolicy.serialize_phase_timeouts(value: Mapping[EnvironmentLifecyclePhase, float]) -> dict[str, float]

validate_phase_timeouts (method)

EnvironmentLifecyclePolicy.validate_phase_timeouts() -> EnvironmentLifecyclePolicy

timeout_for (method)

EnvironmentLifecyclePolicy.timeout_for(phase: EnvironmentLifecyclePhase) -> float

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleProgress`

from cayu.environments import EnvironmentLifecycleProgress

One bounded aggregate lifecycle observation safe for durable events.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`ENVIRONMENT_LIFECYCLE_PROGRESS_SCHEMA_VERSION`
`operation_id`	`str`	`Field(min_length=1, max_length=128)`
`binding_generation_id`	`str \| None`	`Field(default=None, min_length=1, max_length=128)`
`operation`	`EnvironmentLifecycleOperation`	`required`
`phase`	`EnvironmentLifecyclePhase`	`required`
`status`	`EnvironmentLifecycleProgressStatus`	`required`
`event_index`	`StrictInt`	`Field(ge=1, le=MAX_ENVIRONMENT_PROGRESS_EVENTS)`
`elapsed_ms`	`StrictInt`	`Field(ge=0, le=86400000)`
`phase_elapsed_ms`	`StrictInt`	`Field(ge=0, le=86400000)`
`lifecycle_timeout_seconds`	`StrictFloat`	`Field(gt=0, le=86400)`
`phase_timeout_seconds`	`StrictFloat`	`Field(gt=0, le=86400)`
`deadline_enforcement`	`Literal['cooperative_progress_boundary']`	`'cooperative_progress_boundary'`
`deadline_scope`	`Literal['lifecycle', 'phase'] \| None`	`None`
`recovery_disposition`	`Literal['orphaned_stale'] \| None`	`None`
`deadline`	`datetime`	`required`
`last_progress_at`	`datetime`	`required`
`items_completed`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`items_total`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`bytes_completed`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`bytes_total`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`active_count`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`queued_count`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_ENVIRONMENT_PROGRESS_COUNTER)`
`operation_terminal`	`bool`	`False`
`retained_owner`	`bool`	`False`

validate_projection (method)

EnvironmentLifecycleProgress.validate_projection() -> EnvironmentLifecycleProgress

to_payload (method)

EnvironmentLifecycleProgress.to_payload() -> dict[str, object]

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleProgressReporter`

from cayu.environments import EnvironmentLifecycleProgressReporter

Runtime-provided reporter available to environment adapters during lifecycle work.

Bases: Protocol.

policy (property)

EnvironmentLifecycleProgressReporter.policy() -> EnvironmentLifecyclePolicy

Return the frozen policy governing this operation.

report (method)

async EnvironmentLifecycleProgressReporter.report(phase: EnvironmentLifecyclePhase, status: EnvironmentLifecycleProgressStatus, *, items_completed: int | None=None, items_total: int | None=None, bytes_completed: int | None=None, bytes_total: int | None=None, active_count: int | None=None, queued_count: int | None=None) -> EnvironmentLifecycleProgress | None

Publish one aggregate observation, or coalesce it under configured bounds.

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleProgressStatus`

from cayu.environments import EnvironmentLifecycleProgressStatus

Stable disposition for one bounded lifecycle projection.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`STARTED`	`class attribute`	`'started'`
`ADVANCED`	`class attribute`	`'advanced'`
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`
`DEADLINE_EXCEEDED`	`class attribute`	`'deadline_exceeded'`
`RETAINED`	`class attribute`	`'retained'`

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleTransition`

from cayu.environments import EnvironmentLifecycleTransition

One bounded, content-free durable exposure or release observation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`ENVIRONMENT_LIFECYCLE_TRANSITION_SCHEMA_VERSION`
`phase`	`EnvironmentLifecycleTransitionPhase`	`required`
`outcome`	`EnvironmentLifecycleTransitionOutcome`	`required`
`candidate`	`CapabilityIdentity`	`required`
`binding_generation_id`	`str`	`Field(min_length=1, max_length=128)`
`evidence_schema`	`str \| None`	`Field(default=None, min_length=1, max_length=96)`
`evidence_states`	`tuple[CapabilityState, ...]`	`Field(default_factory=tuple, max_length=64)`
`executable_evidence_states`	`tuple[ExecutionExecutableEvidenceState, ...]`	`Field(default_factory=tuple, max_length=64)`
`evidence_valid_until`	`datetime \| None`	`None`
`refusal_codes`	`tuple[CapabilityIdentity, ...]`	`Field(default_factory=tuple, max_length=64)`
`refusal_capabilities`	`tuple[CapabilityIdentity, ...]`	`Field(default_factory=tuple, max_length=64)`
`refusal_executable_sha256`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=64)`
`ownership`	`Literal['runtime', 'factory', 'binding', 'deferred']`	`required`
`release_action`	`Literal['discard', 'preserve'] \| None`	`None`

validate_schema_version (method)

EnvironmentLifecycleTransition.validate_schema_version(value: object) -> object

validate_binding_generation_id (method)

EnvironmentLifecycleTransition.validate_binding_generation_id(value: str) -> str

validate_evidence_schema (method)

EnvironmentLifecycleTransition.validate_evidence_schema(value: str | None) -> str | None

validate_evidence_valid_until_type (method)

EnvironmentLifecycleTransition.validate_evidence_valid_until_type(value: object) -> object

validate_sorted_unique_tokens (method)

EnvironmentLifecycleTransition.validate_sorted_unique_tokens(value: tuple[str, ...], info) -> tuple[str, ...]

validate_sorted_unique_states (method)

EnvironmentLifecycleTransition.validate_sorted_unique_states(value: tuple[str, ...], info) -> tuple[str, ...]

validate_executable_digests (method)

EnvironmentLifecycleTransition.validate_executable_digests(value: tuple[str, ...]) -> tuple[str, ...]

validate_transition (method)

EnvironmentLifecycleTransition.validate_transition() -> EnvironmentLifecycleTransition

to_payload (method)

EnvironmentLifecycleTransition.to_payload() -> dict[str, object]

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleTransitionOutcome`

from cayu.environments import EnvironmentLifecycleTransitionOutcome

Bounded outcomes for a security-relevant lifecycle milestone.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`OBSERVED`	`class attribute`	`'observed'`
`ACCEPTED`	`class attribute`	`'accepted'`
`REFUSED`	`class attribute`	`'refused'`
`COMPLETED`	`class attribute`	`'completed'`
`ADMITTED`	`class attribute`	`'admitted'`
`EXPOSED`	`class attribute`	`'exposed'`
`RELEASED`	`class attribute`	`'released'`
`DEFERRED`	`class attribute`	`'deferred'`
`FAILED`	`class attribute`	`'failed'`

Release source · Runtime guarantees · Capability guides

`EnvironmentLifecycleTransitionPhase`

from cayu.environments import EnvironmentLifecycleTransitionPhase

Security-relevant milestones in the runtime-owned exposure transaction.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`SELECTED`	`class attribute`	`'selected'`
`PREFLIGHT`	`class attribute`	`'preflight'`
`ALLOCATED`	`class attribute`	`'allocated'`
`RECONNECTED`	`class attribute`	`'reconnected'`
`BOUND`	`class attribute`	`'bound'`
`FINAL_EVIDENCE`	`class attribute`	`'final_evidence'`
`ADMISSION`	`class attribute`	`'admission'`
`EXPOSURE`	`class attribute`	`'exposure'`
`RELEASE`	`class attribute`	`'release'`

Release source · Runtime guarantees · Capability guides

`MAX_ENVIRONMENT_PROGRESS_COUNTER`

from cayu.environments import MAX_ENVIRONMENT_PROGRESS_COUNTER

MAX_ENVIRONMENT_PROGRESS_COUNTER = MAX_PORTABLE_JSON_INTEGER

Release source · Runtime guarantees · Capability guides