cayu.artifacts.resources

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.

LocalArtifactResourceOwner

from cayu.artifacts import LocalArtifactResourceOwner

Local durable artifact owner; only exact artifact and manifest selectors qualify.

Bases: ResourceSelectorOwner.

canonical_resource_kinds (property)

LocalArtifactResourceOwner.canonical_resource_kinds() -> tuple[str, ...]

owner (property)

LocalArtifactResourceOwner.owner() -> OwnerRef

canonicalize (method)

LocalArtifactResourceOwner.canonicalize(selector: ResourceSelector) -> ResourceSelector

contains (method)

LocalArtifactResourceOwner.contains(parent: ResourceSelector, child: ResourceSelector) -> bool

init (method)

LocalArtifactResourceOwner.__init__(root: str | os.PathLike[str], *, owner: OwnerRef, artifact_store: ArtifactStore, redactor: SecretRedactor | None=None, preparation_reader: ResourcePreparationReader | None=None) -> None

drain (method)

async LocalArtifactResourceOwner.drain() -> None

Observe retained in-process workers without cancelling their effects.

artifact_selector (method)

LocalArtifactResourceOwner.artifact_selector(store: LocalArtifactStore, owner: OwnerRef, artifact_id: str) -> ResourceSelector

Observe source identity before host registration; this grants no authority.

register_manifest (method)

LocalArtifactResourceOwner.register_manifest(manifest: FolderInputManifest) -> ResourceSelector

Persist trusted folder material and return its exact selector.

authorize (method)

async LocalArtifactResourceOwner.authorize(command: ResourceAcquisitionCommand, *, permit: PermitCommand) -> ResourcePreparationReceipt

Persist trusted bounded preparation before any acquisition dispatch.

acquire (method)

async LocalArtifactResourceOwner.acquire(command: ResourceAcquisitionCommand, *, preparation: ResourcePreparationReceipt | None=None) -> ResourceAcquisitionReceipt

readback (method)

async LocalArtifactResourceOwner.readback(command: ResourceAcquisitionCommand) -> ExactLookup[ResourceAcquisitionReceipt]

release (method)

async LocalArtifactResourceOwner.release(receipt: ResourceAcquisitionReceipt) -> None

settle_preparation (method)

async LocalArtifactResourceOwner.settle_preparation(command: ResourceAcquisitionCommand | ResourceTransferCommand, *, permit: PermitCommand, source_owner: LocalArtifactResourceOwner | None=None) -> ReceivingSettlementReceipt

Exclude or release one exact preparation under its native owner fence.

Cleanup requires independent registered authority. A missing operation is fenced durably before acknowledging exclusion; cancellation or a missing readback never establishes that outcome.

accept_transfer (method)

async LocalArtifactResourceOwner.accept_transfer(command: ResourceTransferCommand, *, source_owner: LocalArtifactResourceOwner, expected_permit: PermitCommand | None=None) -> ResourceTransferReceipt

read_transfer (method)

async LocalArtifactResourceOwner.read_transfer(command: ResourceTransferCommand) -> ExactLookup[ResourceTransferReceipt]

read_preparation (method)

async LocalArtifactResourceOwner.read_preparation(command: ResourceAcquisitionCommand | ResourceTransferCommand) -> ResourcePreparationReceipt

Read exact owner-issued preparation evidence under its fence.

read_material (method)

async LocalArtifactResourceOwner.read_material(expected)

Reconstruct one exact accepted transfer under current native authority.

release_transfer (method)

async LocalArtifactResourceOwner.release_transfer(receipt: ResourceTransferReceipt) -> None

Release destination retention using its exact durable acceptance.

reconcile (method)

async LocalArtifactResourceOwner.reconcile(*, source_owners: tuple[LocalArtifactResourceOwner, ...]=()) -> tuple[str, ...]

release_transferred_source (method)

async LocalArtifactResourceOwner.release_transferred_source(transfer: ResourceTransferReceipt, *, destination_owner: LocalArtifactResourceOwner) -> ResourceAcquisitionReceipt

Release source · Runtime guarantees · Capability guides

MandateResourcePreparationReader

from cayu.artifacts import MandateResourcePreparationReader

Concrete registered receiver using the shared mandate resolver.

Bases: ResourcePreparationReader.

owner (property)

MandateResourcePreparationReader.owner() -> OwnerRef

acquire (method)

async MandateResourcePreparationReader.acquire(command, permit)

revalidate (method)

async MandateResourcePreparationReader.revalidate(command: ResourceAcquisitionCommand | ResourceTransferCommand, lease: ResourcePreparationLease) -> None

Observe current authority without authorizing a later effect.

revalidation_guard (method)

async MandateResourcePreparationReader.revalidation_guard(command, lease)

authorize_release (method)

async MandateResourcePreparationReader.authorize_release(command)

authorize_preparation_cleanup (method)

async MandateResourcePreparationReader.authorize_preparation_cleanup(command, permit)

register_responsibility (method)

async MandateResourcePreparationReader.register_responsibility(command, permit)

transfer_permit (method)

MandateResourcePreparationReader.transfer_permit(command)

settle_responsibility (method)

async MandateResourcePreparationReader.settle_responsibility(command, permit, reader)

init (method)

MandateResourcePreparationReader.__init__(*, owner: ResourceSelectorOwner, resolver: MandateResolver, context: MandateAccessContext, redactor: SecretRedactor, registration: ObjectRef, policy: ObjectRef, artifact_store: ArtifactStore, collaboration_store: CollaborationStore, initialized: CollaborationInitialization, responsibilities: tuple[tuple[ResourceAcquisitionCommand, PermitCommand], ...], transfers: tuple[tuple[ResourceTransferCommand, PermitCommand], ...]=(), transfer_templates: tuple[tuple[ResourceTransferTemplate, PermitCommand], ...]=()) -> None

Release source · Runtime guarantees · Capability guides

resource_operation_digest

from cayu.artifacts import resource_operation_digest

resource_operation_digest(command: ResourceAcquisitionCommand | ResourceTransferCommand | ResourceTransferTemplate) -> str

Release source · Runtime guarantees · Capability guides

ResourceAcquisitionCommand

from cayu.artifacts import ResourceAcquisitionCommand

Bases: ExpectedOperation[ResourceAcquisitionIntent].

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
operation	OperationRef	required
kind	Literal['resource_acquisition']	'resource_acquisition'
schema_version	Literal[1]	RESOURCE_OPERATION_SCHEMA
mode	Literal['acquire']	'acquire'
source	OwnerRef	required
destination	OwnerRef	required
initiator	InitiatorBinding	required
receipt_stage	Literal['acquired']	'acquired'
intent	IntentT	required

bounded_input (method)

ResourceAcquisitionCommand.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceAcquisitionCommand.immutable_fields() -> ContractValue

operation_scope (method)

ResourceAcquisitionCommand.operation_scope() -> ExpectedOperation[IntentT]

exact_owner (method)

ResourceAcquisitionCommand.exact_owner() -> Self

Release source · Runtime guarantees · Capability guides

ResourceAcquisitionIntent

from cayu.artifacts import ResourceAcquisitionIntent

All decision-bearing resource acquisition inputs.

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
unordered_fields	class attribute	frozenset({'allowed_operations'})
selector	ResourceSelector	required
allowed_operations	tuple[Literal['read', 'transfer', 'release'], ...]	Field(min_length=1, max_length=3)
isolation_mode	Literal['local_durable']	'local_durable'
max_materials	StrictInt	Field(ge=1, le=RESOURCE_MAX_MATERIALS)
max_manifest_bytes	StrictInt	Field(ge=1024, le=32 * 1024 * 1024)
max_total_bytes	StrictInt	Field(ge=1, le=4 * 1024 ** 3)
cleanup_owner	OwnerRef	required
policy	ObjectRef	required
deadline_at_ms	StrictInt | None	Field(default=None, ge=1, le=2 ** 53 - 1)

bounded_input (method)

ResourceAcquisitionIntent.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceAcquisitionIntent.immutable_fields() -> ContractValue

validate_identity (method)

ResourceAcquisitionIntent.validate_identity() -> Self

Release source · Runtime guarantees · Capability guides

ResourceAcquisitionReceipt

from cayu.artifacts import ResourceAcquisitionReceipt

Immutable owner-issued evidence of retained exact material.

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
command	ResourceAcquisitionCommand	required
receipt_id	Identifier	required
stage	Literal['pending', 'owned', 'releasing', 'uncertain', 'transferred', 'released']	required
operation_digest	str	Field(pattern='^[0-9a-f]{64}$')
material_ids	tuple[Identifier, ...]	Field(min_length=1, max_length=RESOURCE_MAX_MATERIALS)
content_commitment	str	Field(pattern='^sha256:[0-9a-f]{64}$')
manifest_commitment	str	Field(pattern='^[0-9a-f]{64}$')
material_count	StrictInt	Field(ge=1, le=RESOURCE_MAX_MATERIALS)
total_bytes	StrictInt	Field(ge=0, le=4 * 1024 ** 3)
allowed_operations	tuple[Literal['read', 'transfer', 'release'], ...]	Field(min_length=1, max_length=3)

bounded_input (method)

ResourceAcquisitionReceipt.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceAcquisitionReceipt.immutable_fields() -> ContractValue

exact_shape (method)

ResourceAcquisitionReceipt.exact_shape() -> Self

Release source · Runtime guarantees · Capability guides

ResourceOwnerConflict

from cayu.artifacts import ResourceOwnerConflict

A fixed operation key was reused with different expected input.

Bases: ResourceOwnerError.

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

Release source · Runtime guarantees · Capability guides

ResourceOwnerError

from cayu.artifacts import ResourceOwnerError

The owner cannot establish or reconcile exact resource responsibility.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

ResourceOwnerUnavailable

from cayu.artifacts import ResourceOwnerUnavailable

Durable readback or source material is unavailable.

Bases: ResourceOwnerError.

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

Release source · Runtime guarantees · Capability guides

ResourceOwnerUnsupported

from cayu.artifacts import ResourceOwnerUnsupported

The requested adapter or selector mode is not qualified.

Bases: ResourceOwnerError.

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

Release source · Runtime guarantees · Capability guides

ResourcePreparationAuthorization

from cayu.artifacts import ResourcePreparationAuthorization

Evidence yielded under a registered authority’s revocation guard.

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
command	ResourceAcquisitionCommand | ResourceTransferCommand	required
permit	PermitCommand	required
lease	ResourcePreparationLease	required

bounded_input (method)

ResourcePreparationAuthorization.bounded_input(value: object) -> Any

immutable_fields (method)

ResourcePreparationAuthorization.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

ResourcePreparationLease

from cayu.artifacts import ResourcePreparationLease

Runtime-created, receiver-bound authority; not a caller credential.

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
operation_digest	str	Field(pattern='^[0-9a-f]{64}$')
receiver	OwnerRef	required
resolver_generation	StrictInt	Field(ge=0)
receiver_generation	StrictInt	Field(ge=0)
revocation_generation	StrictInt	Field(ge=0)
expires_at_ms	StrictInt	Field(ge=1)
nonce	str	Field(min_length=16, max_length=128)
authority_sha256	str	Field(pattern='^[0-9a-f]{64}$')
authority_json	str	Field(min_length=2, max_length=65536)
chain_generations	tuple[tuple[ObjectRef, StrictInt], ...]	Field(max_length=16)

bounded_input (method)

ResourcePreparationLease.bounded_input(value: object) -> Any

immutable_fields (method)

ResourcePreparationLease.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

ResourcePreparationReader

from cayu.artifacts import ResourcePreparationReader

Trusted application registration, never selected by operation input.

Implementations authenticate caller identity, the exact retained permit, command, policy, bounds and source revision. Merely validating or echoing these values is not authorization. The guard serializes revocation until exit, performs no acquisition effects, and must not block the event loop. Durable recovery requires re-registration of the same authority.

Bases: ABC.

owner (property)

ResourcePreparationReader.owner() -> OwnerRef

acquire (method)

ResourcePreparationReader.acquire(command: ResourceAcquisitionCommand | ResourceTransferCommand, permit: PermitCommand) -> AbstractAsyncContextManager[ResourcePreparationAuthorization]

revalidate (method)

async ResourcePreparationReader.revalidate(command: ResourceAcquisitionCommand | ResourceTransferCommand, lease: ResourcePreparationLease) -> None

Observe current authority without authorizing a later effect.

revalidation_guard (method)

ResourcePreparationReader.revalidation_guard(command: ResourceAcquisitionCommand | ResourceTransferCommand, lease: ResourcePreparationLease) -> AbstractAsyncContextManager[None]

Serialize revocation through dispatch/publication, not effect settlement.

authorize_release (method)

async ResourcePreparationReader.authorize_release(command: ResourceAcquisitionCommand) -> None

Authenticate current public cleanup authority independently of acquisition expiry.

authorize_preparation_cleanup (method)

async ResourcePreparationReader.authorize_preparation_cleanup(command, permit: PermitCommand) -> None

Authenticate exact registered preparation cleanup, including pre-dispatch.

Releasing an existing receipt alone does not qualify exclusion of a future operation. Unqualified receivers must refuse this extension.

register_responsibility (method)

async ResourcePreparationReader.register_responsibility(command, permit) -> None

transfer_permit (method)

ResourcePreparationReader.transfer_permit(command: ResourceTransferCommand) -> PermitCommand

Resolve exact destination responsibility from trusted registration.

settle_responsibility (method)

async ResourcePreparationReader.settle_responsibility(command, permit, reader: PermitSettlementReader) -> None

Release source · Runtime guarantees · Capability guides

ResourcePreparationReceipt

from cayu.artifacts import ResourcePreparationReceipt

Owner-issued bounded preparation evidence, not caller-mintable authority.

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
operation_digest	str	Field(pattern='^[0-9a-f]{64}$')
owner	OwnerRef	required
command_bytes_sha256	str	Field(pattern='^[0-9a-f]{64}$')
permit	PermitCommand	required
lease	ResourcePreparationLease	required

bounded_input (method)

ResourcePreparationReceipt.bounded_input(value: object) -> Any

immutable_fields (method)

ResourcePreparationReceipt.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

ResourceTransferCommand

from cayu.artifacts import ResourceTransferCommand

Bases: ExpectedOperation[ResourceTransferIntent].

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
operation	OperationRef	required
kind	Literal['resource_transfer']	'resource_transfer'
schema_version	Literal[1]	1
mode	Literal['transfer']	'transfer'
source	OwnerRef	required
destination	OwnerRef	required
initiator	InitiatorBinding	required
receipt_stage	Literal['accepted']	'accepted'
intent	IntentT	required

bounded_input (method)

ResourceTransferCommand.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceTransferCommand.immutable_fields() -> ContractValue

operation_scope (method)

ResourceTransferCommand.operation_scope() -> ExpectedOperation[IntentT]

exact_owner (method)

ResourceTransferCommand.exact_owner() -> Self

Release source · Runtime guarantees · Capability guides

ResourceTransferIntent

from cayu.artifacts import ResourceTransferIntent

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
receipt	ResourceAcquisitionReceipt	required
destination	OwnerRef	required
cleanup_owner	OwnerRef	required
acceptance_generation	Generation	required
expected_material_commitment	str	Field(pattern='^sha256:[0-9a-f]{64}$')

bounded_input (method)

ResourceTransferIntent.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceTransferIntent.immutable_fields() -> ContractValue

exact_transfer (method)

ResourceTransferIntent.exact_transfer() -> Self

Release source · Runtime guarantees · Capability guides

ResourceTransferReceipt

from cayu.artifacts import ResourceTransferReceipt

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
command	ResourceTransferCommand	required
receipt_id	Identifier	required
stage	Literal['pending', 'accepted', 'releasing', 'uncertain', 'released']	required
operation_digest	str	Field(pattern='^[0-9a-f]{64}$')
destination_pin_owner	Identifier	required

bounded_input (method)

ResourceTransferReceipt.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceTransferReceipt.immutable_fields() -> ContractValue

exact_shape (method)

ResourceTransferReceipt.exact_shape() -> Self

Release source · Runtime guarantees · Capability guides

ResourceTransferTemplate

from cayu.artifacts import ResourceTransferTemplate

Pinned registration before its exact acquisition produces a receipt.

Binding only constructs data. The destination’s existing transfer owner must authenticate the complete resulting receipt through the source owner before acquiring any destination pin. A template never renews a mandate.

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
kind	Literal['resource_transfer_template']	'resource_transfer_template'
schema_version	Literal[1]	1
operation	OperationRef	required
source	OwnerRef	required
destination	OwnerRef	required
initiator	InitiatorBinding	required
acquisition	ResourceAcquisitionCommand	required
acceptance_generation	Generation	required

bounded_input (method)

ResourceTransferTemplate.bounded_input(value: object) -> Any

immutable_fields (method)

ResourceTransferTemplate.immutable_fields() -> ContractValue

exact_source (method)

ResourceTransferTemplate.exact_source() -> Self

bind (method)

ResourceTransferTemplate.bind(receipt: ResourceAcquisitionReceipt) -> ResourceTransferCommand

Release source · Runtime guarantees · Capability guides