cayu.immutable_inputs

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.

`DEFAULT_IMMUTABLE_INPUT_MAX_FILE_BYTES`

from cayu.environments import DEFAULT_IMMUTABLE_INPUT_MAX_FILE_BYTES

DEFAULT_IMMUTABLE_INPUT_MAX_FILE_BYTES = 64 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`DEFAULT_IMMUTABLE_INPUT_MAX_FILES`

from cayu.environments import DEFAULT_IMMUTABLE_INPUT_MAX_FILES

DEFAULT_IMMUTABLE_INPUT_MAX_FILES = 100000

Release source · Runtime guarantees · Capability guides

`DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES`

from cayu.environments import DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES

DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`docker_immutable_input_capability`

from cayu.environments import docker_immutable_input_capability

Return Docker’s concrete manager-issued bind-mount capability.

docker_immutable_input_capability() -> ImmutableInputAdapterCapability

Release source · Runtime guarantees · Capability guides

`DockerImmutableInputMount`

from cayu.environments import DockerImmutableInputMount

Opaque manager-issued authority for one exact Docker read-only mount.

Decorators: @dataclass(frozen=True, slots=True, init=False).

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
`source_path`	`str`	`required`
`target_path`	`str`	`required`
`projection_fingerprint`	`str`	`required`
`attachment_id`	`str`	`required`

init (method)

DockerImmutableInputMount.__init__(*_args: object, **_kwargs: object) -> None

Release source · Runtime guarantees · Capability guides

`IMMUTABLE_INPUT_FORMAT_VERSION`

from cayu.environments import IMMUTABLE_INPUT_FORMAT_VERSION

IMMUTABLE_INPUT_FORMAT_VERSION = 'cayu.immutable-tree.v1'

Release source · Runtime guarantees · Capability guides

`ImmutableInputAdapterCapability`

from cayu.environments import ImmutableInputAdapterCapability

Content-free declaration of one adapter’s projection mechanism.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`adapter`	`str`	`Field(max_length=128)`
`capability`	`ImmutableInputProjectionCapability`	`required`
`mechanism`	`str \| None`	`Field(default=None, max_length=128)`
`read_only_enforced`	`StrictBool`	`False`
`shared_materialization`	`StrictBool`	`False`
`durable_recovery`	`StrictBool`	`False`
`explicit_copy_fallback`	`StrictBool`	`False`
`reason_code`	`str \| None`	`Field(default=None, max_length=128)`

validate_adapter (method)

ImmutableInputAdapterCapability.validate_adapter(value: str) -> str

validate_claims (method)

ImmutableInputAdapterCapability.validate_claims() -> Self

Release source · Runtime guarantees · Capability guides

`ImmutableInputAttachment`

from cayu.environments import ImmutableInputAttachment

Durable ownership of a verified materialization by one environment.

Decorators: @dataclass(frozen=True, slots=True, init=False).

Fields and attributes

Name	Type	Default
`attachment_id`	`str`	`required`
`owner_id`	`str`	`required`
`projection`	`ImmutableInputProjection`	`required`
`materialization_path`	`Path`	`required`
`reused`	`bool`	`required`

init (method)

ImmutableInputAttachment.__init__(*_args: object, **_kwargs: object) -> None

docker_mount (method)

ImmutableInputAttachment.docker_mount() -> DockerImmutableInputMount

Release source · Runtime guarantees · Capability guides

`ImmutableInputAttachmentStateError`

from cayu.environments import ImmutableInputAttachmentStateError

An attachment identifier was reused after its durable release boundary.

Bases: RuntimeError.

init (method)

ImmutableInputAttachmentStateError.__init__(attachment_id: str, state: str) -> None

Release source · Runtime guarantees · Capability guides

`ImmutableInputDiagnostic`

from cayu.environments import ImmutableInputDiagnostic

Bounded content-free diagnostics for one shared materialization.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`projection_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`content_root`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`logical_bytes`	`StrictInt`	`Field(ge=0)`
`physical_bytes`	`StrictInt`	`Field(ge=0)`
`reference_count`	`StrictInt`	`Field(ge=0)`
`attachment_count`	`StrictInt`	`Field(ge=0)`
`reuse_count`	`StrictInt`	`Field(ge=0)`
`cleanup_state`	`Literal['retained', 'eligible', 'collecting', 'removed']`	`required`
`wait_reason`	`Literal['none', 'materialization_lock']`	`'none'`

Release source · Runtime guarantees · Capability guides

`ImmutableInputMutationError`

from cayu.environments import ImmutableInputMutationError

A supposedly immutable materialization no longer matches its identity.

Bases: RuntimeError.

init (method)

ImmutableInputMutationError.__init__(projection_fingerprint: str, reason_code: str) -> None

Release source · Runtime guarantees · Capability guides

`ImmutableInputProjection`

from cayu.environments import ImmutableInputProjection

Exact content and policy identity for one read-only target projection.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`content_root`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`logical_bytes`	`StrictInt`	`Field(ge=0, le=DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES)`
`file_count`	`StrictInt`	`Field(ge=0, le=DEFAULT_IMMUTABLE_INPUT_MAX_FILES)`
`target_path`	`str`	`Field(max_length=4096)`
`policy_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`runtime_compatibility_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`authorization_scope_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`format_version`	`Literal['cayu.immutable-tree.v1']`	`IMMUTABLE_INPUT_FORMAT_VERSION`
`max_files`	`StrictInt`	`Field(default=DEFAULT_IMMUTABLE_INPUT_MAX_FILES, ge=1)`
`max_file_bytes`	`StrictInt`	`Field(default=DEFAULT_IMMUTABLE_INPUT_MAX_FILE_BYTES, ge=1)`
`max_total_bytes`	`StrictInt`	`Field(default=DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES, ge=1)`

validate_sha256 (method)

ImmutableInputProjection.validate_sha256(value: str, info: Any) -> str

validate_target_path (method)

ImmutableInputProjection.validate_target_path(value: str) -> str

validate_bounds (method)

ImmutableInputProjection.validate_bounds() -> Self

fingerprint (property)

ImmutableInputProjection.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

`ImmutableInputProjectionCapability`

from cayu.environments import ImmutableInputProjectionCapability

Truthful environment-input behavior supplied by one adapter.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`SHARED_READ_ONLY`	`class attribute`	`'shared_read_only'`
`MUTABLE_SYNC_BINDING`	`class attribute`	`'mutable_sync_binding'`
`BOUNDED_COPY`	`class attribute`	`'mutable_sync_binding'`
`WORKSPACE_MATERIALIZATION`	`class attribute`	`'workspace_materialization'`
`UNSUPPORTED`	`class attribute`	`'unsupported'`

Release source · Runtime guarantees · Capability guides

`ImmutableInputProjectionUnsupportedError`

from cayu.environments import ImmutableInputProjectionUnsupportedError

An adapter cannot provide the requested immutable-input guarantees.

Bases: RuntimeError.

init (method)

ImmutableInputProjectionUnsupportedError.__init__(reason_code: str) -> None

Release source · Runtime guarantees · Capability guides

`ImmutableInputStore`

from cayu.environments import ImmutableInputStore

Durable convergent registry and materializer for immutable local trees.

init (method)

ImmutableInputStore.__init__(root: str | os.PathLike[str]) -> None

reserve_allocation_sync (method)

ImmutableInputStore.reserve_allocation_sync(scope_id: str, projection_fingerprints: tuple[str, ...]) -> str

Reserve a durable incarnation until all its attachments are released.

Missing admissions and closing attachments retain the same incarnation. Callers must use the returned identity as their attachment owner ID.

attach (method)

async ImmutableInputStore.attach(source: LocalImmutableInput, *, attachment_id: str, owner_id: str) -> ImmutableInputAttachment

Materialize once and durably attach one exact environment owner.

attach_sync (method)

ImmutableInputStore.attach_sync(source: LocalImmutableInput, *, attachment_id: str, owner_id: str) -> ImmutableInputAttachment

release_allocation_sync (method)

ImmutableInputStore.release_allocation_sync(owner_id: str) -> None

Terminalize an exact allocation, including admissions not yet written.

The caller must first confirm disposal of the owned external resource.

release (method)

async ImmutableInputStore.release(attachment_id: str) -> None

mark_container_closing (method)

async ImmutableInputStore.mark_container_closing(attachments: tuple[ImmutableInputAttachment, ...], *, container_id: str) -> None

mark_container_closing_sync (method)

ImmutableInputStore.mark_container_closing_sync(attachments: tuple[ImmutableInputAttachment, ...], *, container_id: str) -> None

interrupted_cleanup_container_id (method)

async ImmutableInputStore.interrupted_cleanup_container_id(attachment_ids: tuple[str, ...]) -> str | None

interrupted_cleanup_container_id_sync (method)

ImmutableInputStore.interrupted_cleanup_container_id_sync(attachment_ids: tuple[str, ...]) -> str | None

reconcile_interrupted_container_cleanup (method)

async ImmutableInputStore.reconcile_interrupted_container_cleanup(attachment_ids: tuple[str, ...], *, container_id: str, container_exists: bool) -> bool

reconcile_interrupted_container_cleanup_sync (method)

ImmutableInputStore.reconcile_interrupted_container_cleanup_sync(attachment_ids: tuple[str, ...], *, container_id: str, container_exists: bool) -> bool

release_sync (method)

ImmutableInputStore.release_sync(attachment_id: str) -> None

inspect (method)

ImmutableInputStore.inspect() -> tuple[ImmutableInputDiagnostic, ...]

collect (method)

ImmutableInputStore.collect(projection_fingerprint: str) -> bool

Remove one unreferenced materialization; active identities fail closed.

Release source · Runtime guarantees · Capability guides

`inspect_local_immutable_input`

from cayu.environments import inspect_local_immutable_input

Inspect a bounded local tree and return its exact projection identity.

inspect_local_immutable_input(root: str | os.PathLike[str], *, target_path: str, policy_fingerprint: str, runtime_compatibility_fingerprint: str, authorization_scope_fingerprint: str, max_files: int=DEFAULT_IMMUTABLE_INPUT_MAX_FILES, max_file_bytes: int=DEFAULT_IMMUTABLE_INPUT_MAX_FILE_BYTES, max_total_bytes: int=DEFAULT_IMMUTABLE_INPUT_MAX_TOTAL_BYTES) -> LocalImmutableInput

Release source · Runtime guarantees · Capability guides

`LocalImmutableInput`

from cayu.environments import LocalImmutableInput

A local source whose bytes must verify against an exact projection.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Name	Type	Default
`root`	`Path`	`required`
`projection`	`ImmutableInputProjection`	`required`

Release source · Runtime guarantees · Capability guides

`require_immutable_input_projection`

from cayu.environments import require_immutable_input_projection

Fail closed unless an adapter can project or an explicit copy fallback is allowed.

require_immutable_input_projection(capability: ImmutableInputAdapterCapability, *, allow_bounded_copy_fallback: bool=False) -> ImmutableInputAdapterCapability

Release source · Runtime guarantees · Capability guides