cayu.environments.admission

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.

`evaluate_execution_admission`

from cayu.environments import evaluate_execution_admission

Evaluate one explicit candidate without selecting or falling back to another.

evaluate_execution_admission(*, candidate: str, requirements: ExecutionRequirements, evidence: ExecutionCapabilityEvidence | Mapping[str, object] | None, stage: ExecutionAdmissionStage='pre_exposure', now: datetime | None=None) -> ExecutionAdmissionDecision

Release source · Runtime guarantees · Capability guides

`EXECUTION_CAPABILITY_EVIDENCE_SCHEMA`

from cayu.environments import EXECUTION_CAPABILITY_EVIDENCE_SCHEMA

EXECUTION_CAPABILITY_EVIDENCE_SCHEMA = 'cayu.execution_capabilities.v1'

Release source · Runtime guarantees · Capability guides

`EXECUTION_LIVE_EVIDENCE_MAX_TTL_SECONDS`

from cayu.environments import EXECUTION_LIVE_EVIDENCE_MAX_TTL_SECONDS

EXECUTION_LIVE_EVIDENCE_MAX_TTL_SECONDS = 300

Release source · Runtime guarantees · Capability guides

`EXECUTION_TOOL_REQUIREMENT_EVIDENCE_SCHEMA`

from cayu.environments import EXECUTION_TOOL_REQUIREMENT_EVIDENCE_SCHEMA

EXECUTION_TOOL_REQUIREMENT_EVIDENCE_SCHEMA = 'cayu.execution_tool_requirements.v1'

Release source · Runtime guarantees · Capability guides

`ExecutionAdmissionCandidate`

from cayu.environments import ExecutionAdmissionCandidate

Explicit execution identity and evidence supplied by its integration.

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
`candidate`	`CapabilityIdentity`	`required`
`evidence`	`ExecutionCapabilityEvidence`	`required`

validate_evidence_subject (method)

ExecutionAdmissionCandidate.validate_evidence_subject() -> Self

Release source · Runtime guarantees · Capability guides

`ExecutionAdmissionDecision`

from cayu.environments import ExecutionAdmissionDecision

Complete admitted/refused result for one explicit candidate and stage.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`status`	`ExecutionAdmissionStatus`	`required`
`stage`	`ExecutionAdmissionStage`	`required`
`candidate`	`CapabilityIdentity`	`required`
`requirements`	`ExecutionRequirements`	`required`
`evidence_schema`	`str \| None`	`None`
`evidence`	`ExecutionCapabilityEvidence \| None`	`None`
`refusals`	`tuple[ExecutionAdmissionRefusal, ...]`	`()`

validate_status_refusals (method)

ExecutionAdmissionDecision.validate_status_refusals() -> Self

require_admitted (method)

ExecutionAdmissionDecision.require_admitted() -> Self

Return an admitted decision or raise its structured refusal.

Release source · Runtime guarantees · Capability guides

`ExecutionAdmissionError`

from cayu.environments import ExecutionAdmissionError

An execution candidate failed capability-based admission.

Bases: RuntimeError.

init (method)

ExecutionAdmissionError.__init__(decision: ExecutionAdmissionDecision) -> None

Release source · Runtime guarantees · Capability guides

`ExecutionAdmissionRefusal`

from cayu.environments import ExecutionAdmissionRefusal

One stable reason an explicit execution candidate was not admitted.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`code`	`ExecutionAdmissionRefusalCode`	`required`
`tool_name`	`str \| None`	`Field(default=None, max_length=512)`
`requirement_name`	`str \| None`	`Field(default=None, max_length=96)`
`capability`	`CapabilityIdentity \| None`	`None`
`executable`	`str \| None`	`Field(default=None, max_length=4096)`
`required_state`	`MinimumExecutionEvidence \| None`	`None`
`observed_state`	`ExecutionObservedCapabilityState \| None`	`None`
`reason_code`	`CapabilityIdentity \| None`	`None`
`remediation_code`	`CapabilityIdentity \| None`	`None`

validate_optional_executable (method)

ExecutionAdmissionRefusal.validate_optional_executable(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`ExecutionCapabilityClaim`

from cayu.environments import ExecutionCapabilityClaim

One bounded capability fact used by execution admission.

Bases: CapabilityClaim.

Fields and attributes

Name	Type	Default
`capability`	`CapabilityIdentity`	`required`
`adapter_details`	`tuple[CapabilityDetail, ...]`	`Field(default_factory=tuple, max_length=MAX_CAPABILITY_DETAILS)`
`state`	`CapabilityState`	`required`
`proof_source`	`CapabilityProofSource`	`required`
`observation`	`CapabilityObservation`	`required`
`reason_code`	`CapabilityIdentity \| None`	`None`
`remediation_code`	`CapabilityIdentity \| None`	`None`
`observed_at`	`datetime \| None`	`None`
`valid_until`	`datetime \| None`	`None`

validate_detail_names (method)

ExecutionCapabilityClaim.validate_detail_names() -> Self

validate_state_fields (method)

ExecutionCapabilityClaim.validate_state_fields() -> Self

declared (method)

ExecutionCapabilityClaim.declared(capability: str) -> Self

available (method)

ExecutionCapabilityClaim.available(capability: str) -> Self

live_verified (method)

ExecutionCapabilityClaim.live_verified(capability: str, *, observation: Literal['denied', 'reachable', 'supported'], observed_at: datetime, valid_until: datetime) -> Self

unverified (method)

ExecutionCapabilityClaim.unverified(capability: str, *, reason_code: str, remediation_code: str) -> Self

unsupported (method)

ExecutionCapabilityClaim.unsupported(capability: str, *, reason_code: str, remediation_code: str) -> Self

Release source · Runtime guarantees · Capability guides

`ExecutionCapabilityEvidence`

from cayu.environments import ExecutionCapabilityEvidence

Versioned evidence for one explicitly selected execution candidate.

Bases: CapabilityEvidence.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal['cayu.execution_capabilities.v1']`	`Field(default=EXECUTION_CAPABILITY_EVIDENCE_SCHEMA, alias='schema')`
`subject`	`CapabilityIdentity`	`required`
`claims`	`tuple[ExecutionCapabilityClaim, ...]`	`Field(default_factory=tuple, max_length=64)`
`unclaimed_reason_code`	`CapabilityIdentity \| None`	`None`
`environment_fingerprint`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`image_fingerprint`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`toolchain_profile_fingerprint`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`tool_requirements`	`ExecutionToolRequirementEvidence \| None`	`None`

validate_claims (method)

ExecutionCapabilityEvidence.validate_claims() -> Self

unclaimed (method)

ExecutionCapabilityEvidence.unclaimed(subject: str, *, reason_code: str='capabilities_unclaimed') -> Self

claim_for (method)

ExecutionCapabilityEvidence.claim_for(capability: str) -> ExecutionCapabilityClaim | None

state_for (method)

ExecutionCapabilityEvidence.state_for(capability: str) -> CapabilityState | Literal['unclaimed']

to_metadata (method)

ExecutionCapabilityEvidence.to_metadata() -> dict[str, object]

Return complete bounded execution evidence for durable diagnostics.

validate_tool_requirement_identity (method)

ExecutionCapabilityEvidence.validate_tool_requirement_identity() -> Self

Release source · Runtime guarantees · Capability guides

`ExecutionEnvironmentAuthority`

from cayu.environments import ExecutionEnvironmentAuthority

Opaque identity for one exact environment security boundary.

Integrations carry this value from side-effect-free construction evidence to the materialized runner. identity is process-local and binds one concrete factory or runner. profile_identity exists only when the application has supplied a stable versioned declaration that can be reconstructed after restart; it never replaces the exact live identity used at dispatch.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`identity`	`str`	`Field(max_length=96)`
`profile_identity`	`str \| None`	`Field(default=None, max_length=96)`

validate_identity (method)

ExecutionEnvironmentAuthority.validate_identity(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`ExecutionEvidenceOverride`

from cayu.environments import ExecutionEvidenceOverride

A capability-specific minimum that overrides the workload default.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`capability`	`CapabilityIdentity`	`required`
`minimum_evidence`	`MinimumExecutionEvidence`	`required`

Release source · Runtime guarantees · Capability guides

`ExecutionExecutableEvidence`

from cayu.environments import ExecutionExecutableEvidence

One bounded executable-availability fact for the exact final environment.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`executable`	`str`	`Field(max_length=4096)`
`state`	`ExecutionExecutableEvidenceState`	`required`
`requirement_fingerprint`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`observed_at`	`datetime \| None`	`None`
`valid_until`	`datetime \| None`	`None`
`reason_code`	`str \| None`	`Field(default=None, max_length=96)`
`remediation_code`	`str \| None`	`Field(default=None, max_length=96)`

validate_executable (method)

ExecutionExecutableEvidence.validate_executable(value: str) -> str

validate_optional_code (method)

ExecutionExecutableEvidence.validate_optional_code(value: str | None, info) -> str | None

validate_state_fields (method)

ExecutionExecutableEvidence.validate_state_fields() -> Self

Release source · Runtime guarantees · Capability guides

`ExecutionRequirements`

from cayu.environments import ExecutionRequirements

Provider-neutral security and lifecycle requirements for one workload.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`code_trust`	`ExecutionCodeTrust`	`'trusted'`
`real_secret_visibility`	`ExecutionSecretVisibility`	`'allowed'`
`network_access`	`ExecutionNetworkAccess`	`'unrestricted'`
`guest_privilege`	`ExecutionGuestPrivilege`	`'unrestricted'`
`host_filesystem`	`ExecutionHostFilesystem`	`'unrestricted'`
`cancellation`	`ExecutionCancellation`	`'best_effort'`
`cleanup`	`ExecutionCleanup`	`'best_effort'`
`durability`	`ExecutionDurability`	`'ephemeral'`
`minimum_evidence`	`MinimumExecutionEvidence`	`'declared'`
`evidence_overrides`	`tuple[ExecutionEvidenceOverride, ...]`	`Field(default_factory=tuple, max_length=64)`
`required_executables`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=64)`
`tool_requirements`	`tuple[ExecutionToolRequirement, ...]`	`Field(default_factory=tuple, max_length=64)`

copy_tool_requirements (method)

ExecutionRequirements.copy_tool_requirements(value: object) -> tuple[ExecutionToolRequirement, ...]

validate_tool_requirements (method)

ExecutionRequirements.validate_tool_requirements() -> Self

validate_required_executables (method)

ExecutionRequirements.validate_required_executables(value: tuple[str, ...]) -> tuple[str, ...]

validate_evidence_overrides (method)

ExecutionRequirements.validate_evidence_overrides() -> Self

trusted (method)

ExecutionRequirements.trusted(**overrides: object) -> Self

Build requirements for an explicitly trusted workload.

untrusted (method)

ExecutionRequirements.untrusted(**overrides: object) -> Self

Build fail-closed defaults for model-authored or otherwise untrusted code.

required_capabilities (method)

ExecutionRequirements.required_capabilities() -> tuple[str, ...]

Project the configured workload policy into explicit capability names.

executable_probes (method)

ExecutionRequirements.executable_probes() -> tuple[ToolExecutableRequirement, ...]

Return the deduplicated process probes required by executable alternatives.

executable_names (method)

ExecutionRequirements.executable_names() -> tuple[str, ...]

Return bounded executable evidence inputs without turning OR clauses into AND.

minimum_evidence_for (method)

ExecutionRequirements.minimum_evidence_for(capability: str) -> MinimumExecutionEvidence

Return the configured evidence minimum for one required capability.

Release source · Runtime guarantees · Capability guides

`ExecutionToolRequirement`

from cayu.environments import ExecutionToolRequirement

A tool-owned clause composed into the common workload admission policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tool_name`	`str`	`Field(min_length=1, max_length=512)`
`requirement`	`ToolExecutionRequirement`	`required`

validate_tool_name (method)

ExecutionToolRequirement.validate_tool_name(value: str) -> str

Release source · Runtime guarantees · Capability guides

`ExecutionToolRequirementEvidence`

from cayu.environments import ExecutionToolRequirementEvidence

Versioned evidence for tool dependencies in one exact environment.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal['cayu.execution_tool_requirements.v1']`	`Field(default=EXECUTION_TOOL_REQUIREMENT_EVIDENCE_SCHEMA, alias='schema')`
`environment_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`image_fingerprint`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`executables`	`tuple[ExecutionExecutableEvidence, ...]`	`Field(default_factory=tuple, max_length=64)`

validate_unique_executables (method)

ExecutionToolRequirementEvidence.validate_unique_executables() -> Self

executable_for (method)

ExecutionToolRequirementEvidence.executable_for(executable: str) -> ExecutionExecutableEvidence | None

Release source · Runtime guarantees · Capability guides