cayu.workspaces.branches

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.

RemoteWorkspaceBranchAuthorityProvider

from cayu.workspaces import RemoteWorkspaceBranchAuthorityProvider

Own the complete live invocation authority for a remote branch.

Binding identity alone cannot fence a replaced session worker when an environment allocation remains attached across run epochs. Durable remote branch implementations therefore require one atomic claim over both the binding generation and the session/run authority.

Decorators: @runtime_checkable.

Bases: WorkspaceBranchBindingAuthorityProvider, Protocol.

claim_scope (property)

RemoteWorkspaceBranchAuthorityProvider.claim_scope() -> WorkspaceBranchBindingAuthorityClaimScope

Declare whether claims exclude owners only locally or across processes.

call (method)

RemoteWorkspaceBranchAuthorityProvider.__call__() -> WorkspaceBranchBindingAuthority

Return the current binding authority.

claim (method)

RemoteWorkspaceBranchAuthorityProvider.claim(expected: WorkspaceBranchBindingAuthority) -> WorkspaceBranchBindingAuthorityClaim

Keep expected current until the guarded operation settles.

The claim must be transferable across task contexts. Its release method may be called by a later settlement task and must retain ownership when it raises so Cayu can retry it.

current_operation_authority (method)

RemoteWorkspaceBranchAuthorityProvider.current_operation_authority(session_id: str) -> WorkspaceBranchAuthority

Return the complete currently admitted authority for session_id.

claim_operation (method)

RemoteWorkspaceBranchAuthorityProvider.claim_operation(expected: WorkspaceBranchAuthority) -> WorkspaceBranchBindingAuthorityClaim

Keep the exact invocation and binding authority current until release.

Release source · Runtime guarantees · Capability guides

WorkspaceBranch

from cayu.workspaces import WorkspaceBranch

An isolated workspace view with explicit publication.

Bases: Workspace.

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
id	str	required

reference_binding (method)

WorkspaceBranch.reference_binding() -> WorkspaceReferenceBinding

Bind application data to this workspace incarnation.

The default is object-lifetime scoped and fails closed after reopening. Durable adapters may override this method only when they can preserve an incarnation across recovery and rotate it on replacement. Never restore a generation from the application reference being validated.

read_bytes (method)

async WorkspaceBranch.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> WorkspaceReadResult

Read a byte page from the workspace.

Complete offset-zero snapshots expose an opaque revision suitable for a later conditional mutation. Backends must not expose a revision for a partial page. An offset equal to the current file size returns an empty page; an offset beyond it raises WorkspaceReadOffsetError.

bounded_read_limit (method)

WorkspaceBranch.bounded_read_limit(max_bytes: int) -> int

Resolve a hard read ceiling without loosening backend defaults.

Return a positive integer no greater than max_bytes. Backends with their own finite default read limit must return the smaller value; backends without one return max_bytes. Callers use this before read_bytes when a safety bound must compose with backend policy.

write_bytes (method)

async WorkspaceBranch.write_bytes(path: str, content: bytes) -> None

Write a file into the workspace.

delete (method)

async WorkspaceBranch.delete(path: str) -> None

Delete a file from the workspace if it exists.

create_bytes (method)

async WorkspaceBranch.create_bytes(path: str, content: bytes) -> WorkspaceMutationResult

Create a missing file without overwriting an existing path.

replace_bytes (method)

async WorkspaceBranch.replace_bytes(path: str, content: bytes, *, expected_revision: str) -> WorkspaceMutationResult

Replace a file only when its current opaque revision matches.

delete_if_revision (method)

async WorkspaceBranch.delete_if_revision(path: str, *, expected_revision: str) -> WorkspaceMutationResult

Delete a file only when its current opaque revision matches.

require_absent (method)

async WorkspaceBranch.require_absent(path: str) -> None

Authoritatively preflight that one workspace path is absent.

This is an optional compatibility capability. Implementations used by the structured patch tool must override it; the later create or move still retains its own conditional absence precondition because this preflight is not a lock.

move_if_revision (method)

async WorkspaceBranch.move_if_revision(source_path: str, destination_path: str, *, expected_source_revision: str, require_destination_absent: bool=True) -> WorkspaceMoveResult

Conditionally move one regular file within this workspace.

Implementations must never overwrite the destination and must report their actual move fidelity. Unsupported adapters fail explicitly; they never fall back to shell execution or an unlabelled copy/delete pair.

list (method)

async WorkspaceBranch.list(pattern: str='**/*', *, limit: int | None=None) -> WorkspaceListResult

List files in the workspace.

Every backend must match pattern against workspace-relative POSIX file paths with the normative semantics of matches_list_pattern.

list_git_entries (method)

async WorkspaceBranch.list_git_entries(*, limit: int) -> WorkspaceGitEntryListResult

List regular files and symlinks without following either entry type.

resource_key (property)

WorkspaceBranch.resource_key() -> tuple[object, ...] | None

Stable, hashable token identifying the underlying resource (filesystem/sandbox area) this workspace reads and writes, so callers can tell whether two Workspace objects point at the SAME place.

Returns None when identity cannot be determined. SyncBinding then refuses to bind rather than risk clearing a target that is actually the source; override this in a custom Workspace to return a stable identity token and enable that safety check.

tar_copy_policy_identity (method)

WorkspaceBranch.tar_copy_policy_identity() -> tuple[object, ...] | None

Return an exact, content-free identity for tar copy security policy.

SyncBinding only shares a sealed archive when both adapters opt in with stable identities. Implementations must change the identity whenever path exclusions, archive parsing, or extraction policy changes. None conservatively disables sharing for this adapter.

bounded_tar_stream_reader (method)

WorkspaceBranch.bounded_tar_stream_reader() -> BoundedTarStreamReader | None

Return an explicit bounded streaming-tar reader capability, if any.

tar_stream_writer (method)

WorkspaceBranch.tar_stream_writer() -> TarStreamWriter | None

Return an explicit streaming-tar writer capability, if any.

branch_capabilities (method)

WorkspaceBranch.branch_capabilities() -> WorkspaceBranchCapabilities

Return explicit workspace-branch guarantees for this adapter.

Unsupported is the compatibility default. Capability must be declared by the exact adapter instance and is never inferred from adjacent filesystem, snapshot, runner, sync, reconnect, or Git behavior.

branch_lifecycle_summary (method)

WorkspaceBranch.branch_lifecycle_summary() -> WorkspaceBranchLifecycleSummary

Return bounded lifecycle states for branch handles attached here.

create_branch (method)

async WorkspaceBranch.create_branch(request: WorkspaceBranchRequest) -> WorkspaceBranchCreationResult

Create an isolated bounded workspace branch when supported.

Branching is an optional capability rather than an abstract workspace requirement. Backends that do not implement the complete isolation and publication contract return a typed unsupported result.

branch_id (property)

WorkspaceBranch.branch_id() -> str

Stable identity for this branch.

lifecycle_status (property)

WorkspaceBranch.lifecycle_status() -> WorkspaceBranchLifecycleStatus

Current attached lifecycle state.

changes (method)

async WorkspaceBranch.changes() -> WorkspaceBranchChangeSet

Return the exact deterministic net change set.

publish (method)

async WorkspaceBranch.publish(request: WorkspaceBranchPublicationRequest) -> WorkspaceBranchPublicationResult

Publish the exact requested change set or leave the source unchanged.

rollback (method)

async WorkspaceBranch.rollback(request: WorkspaceBranchRollbackRequest | None=None) -> WorkspaceBranchRollbackResult

Discard the complete private branch without modifying its source.

Release source · Runtime guarantees · Capability guides

WorkspaceBranchAuthority

from cayu.workspaces import WorkspaceBranchAuthority

Durable creation and fencing authority supplied by the owning runtime.

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
session_id	str	Field(max_length=512)
expected_run_epoch	StrictInt	Field(ge=0)
environment_name	str	Field(max_length=256)
binding_generation	str	Field(max_length=512)
binding_identity	str	Field(max_length=512)
creating_authority	str	Field(max_length=512)
resource_policy	str	Field(max_length=512)

validate_authority (method)

WorkspaceBranchAuthority.validate_authority(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchBindingAuthority

from cayu.workspaces import WorkspaceBranchBindingAuthority

The binding identity that is live for a local workspace right now.

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
environment_name	str	Field(max_length=256)
binding_generation	str	Field(max_length=512)
binding_identity	str	Field(max_length=512)

validate_authority (method)

WorkspaceBranchBindingAuthority.validate_authority(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchBindingAuthorityClaim

from cayu.workspaces import WorkspaceBranchBindingAuthorityClaim

One transferable claim on an exact live workspace binding generation.

Cayu may retain the claim after its initiating task returns and release it from a later settlement task. A failed release remains owned and may be retried.

Decorators: @runtime_checkable.

Bases: Protocol.

release (method)

WorkspaceBranchBindingAuthorityClaim.release() -> None

Release the claim, or raise without abandoning its ownership.

Release source · Runtime guarantees · Capability guides

WorkspaceBranchBindingAuthorityClaimScope

from cayu.workspaces import WorkspaceBranchBindingAuthorityClaimScope

Where a binding-generation provider keeps exclusion authority.

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
PROCESS_LOCAL	class attribute	'process_local'
DURABLE	class attribute	'durable'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchBindingAuthorityProvider

from cayu.workspaces import WorkspaceBranchBindingAuthorityProvider

Own one live binding generation and its in-flight branch claims.

A successful claim() is the positive authority evidence for the whole guarded operation. That operation does not call the provider again, acquire a nested claim, or invoke it from an off-thread commit guard before the claim is released.

Decorators: @runtime_checkable.

Bases: Protocol.

claim_scope (property)

WorkspaceBranchBindingAuthorityProvider.claim_scope() -> WorkspaceBranchBindingAuthorityClaimScope

Declare whether claims exclude owners only locally or across processes.

call (method)

WorkspaceBranchBindingAuthorityProvider.__call__() -> WorkspaceBranchBindingAuthority

Return the current binding authority.

claim (method)

WorkspaceBranchBindingAuthorityProvider.claim(expected: WorkspaceBranchBindingAuthority) -> WorkspaceBranchBindingAuthorityClaim

Keep expected current until the guarded operation settles.

The claim must be transferable across task contexts. Its release method may be called by a later settlement task and must retain ownership when it raises so Cayu can retry it.

Release source · Runtime guarantees · Capability guides

WorkspaceBranchBindingAuthorityRegistry

from cayu.workspaces import WorkspaceBranchBindingAuthorityRegistry

Process-local owner for one replaceable workspace binding generation.

init (method)

WorkspaceBranchBindingAuthorityRegistry.__init__(authority: WorkspaceBranchBindingAuthority) -> None

claim_scope (property)

WorkspaceBranchBindingAuthorityRegistry.claim_scope() -> WorkspaceBranchBindingAuthorityClaimScope

call (method)

WorkspaceBranchBindingAuthorityRegistry.__call__() -> WorkspaceBranchBindingAuthority

claim (method)

WorkspaceBranchBindingAuthorityRegistry.claim(expected: WorkspaceBranchBindingAuthority) -> WorkspaceBranchBindingAuthorityClaim

authorize_operation (method)

WorkspaceBranchBindingAuthorityRegistry.authorize_operation(authority: WorkspaceBranchAuthority) -> None

Make one complete invocation authority current for its session.

This process-local registry is primarily a deterministic owner and test/reference implementation. Cross-process implementations must make the same update and subsequent claims atomic in their durable domain.

current_operation_authority (method)

WorkspaceBranchBindingAuthorityRegistry.current_operation_authority(session_id: str) -> WorkspaceBranchAuthority

claim_operation (method)

WorkspaceBranchBindingAuthorityRegistry.claim_operation(expected: WorkspaceBranchAuthority) -> WorkspaceBranchBindingAuthorityClaim

replace (method)

WorkspaceBranchBindingAuthorityRegistry.replace(authority: WorkspaceBranchBindingAuthority) -> None

Release source · Runtime guarantees · Capability guides

WorkspaceBranchCapabilities

from cayu.workspaces import WorkspaceBranchCapabilities

Bounded, provider-neutral branch guarantees for one workspace adapter.

Capability evidence is declarative. Callers must not infer support from a runner, filesystem access, snapshots, reconnectability, sync bindings, or Git availability.

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
isolation	StrictBool	False
net_changes	StrictBool	False
publication	WorkspaceBranchPublicationStrength	WorkspaceBranchPublicationStrength.UNSUPPORTED
recovery	WorkspaceBranchRecoveryStrength	WorkspaceBranchRecoveryStrength.UNSUPPORTED
retention	WorkspaceBranchRetentionStrength	WorkspaceBranchRetentionStrength.UNSUPPORTED
lifecycle_inspection	WorkspaceBranchLifecycleInspection	WorkspaceBranchLifecycleInspection.UNSUPPORTED
detail_code	str	Field(default='workspace_branching_unsupported', max_length=256)

validate_detail_code (method)

WorkspaceBranchCapabilities.validate_detail_code(value: str) -> str

validate_capability_shape (method)

WorkspaceBranchCapabilities.validate_capability_shape() -> WorkspaceBranchCapabilities

Release source · Runtime guarantees · Capability guides

WorkspaceBranchChange

from cayu.workspaces import WorkspaceBranchChange

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
path	str	required
operation	WorkspaceBranchChangeOperation	required
before	WorkspaceBranchContentIdentity | None	None
after	WorkspaceBranchContentIdentity | None	None

validate_path (method)

WorkspaceBranchChange.validate_path(value: str) -> str

validate_change (method)

WorkspaceBranchChange.validate_change() -> WorkspaceBranchChange

Release source · Runtime guarantees · Capability guides

WorkspaceBranchChangeSet

from cayu.workspaces import WorkspaceBranchChangeSet

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
branch_id	str	required
source	WorkspaceIdentity	required
baseline_revision	str	required
changes	tuple[WorkspaceBranchChange, ...]	required
digest	str	required

validate_text (method)

WorkspaceBranchChangeSet.validate_text(value: str, info) -> str

validate_digest (method)

WorkspaceBranchChangeSet.validate_digest(value: str) -> str

validate_order_and_digest (method)

WorkspaceBranchChangeSet.validate_order_and_digest() -> WorkspaceBranchChangeSet

Release source · Runtime guarantees · Capability guides

WorkspaceBranchClosedError

from cayu.workspaces import WorkspaceBranchClosedError

A terminal or expired workspace branch cannot accept this operation.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

WorkspaceBranchConflict

from cayu.workspaces import WorkspaceBranchConflict

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
path	str	required
expected	WorkspaceBranchContentIdentity | None	None
actual	WorkspaceBranchContentIdentity | None	None
actual_kind	Literal['missing', 'file', 'directory', 'symlink', 'special']	required

validate_path (method)

WorkspaceBranchConflict.validate_path(value: str) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchContentIdentity

from cayu.workspaces import WorkspaceBranchContentIdentity

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
sha256	str	required
bytes	StrictInt	Field(ge=0)

validate_sha256 (method)

WorkspaceBranchContentIdentity.validate_sha256(value: str) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchCreationResult

from cayu.workspaces import WorkspaceBranchCreationResult

Decorators: @dataclass(frozen=True).

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
status	WorkspaceBranchOutcomeStatus	required
branch	WorkspaceBranch | None	required
evidence	WorkspaceBranchEvidence	required
conflicts	tuple[WorkspaceBranchConflict, ...]	()

Release source · Runtime guarantees · Capability guides

WorkspaceBranchDurableState

from cayu.workspaces import WorkspaceBranchDurableState

Reconstructible lifecycle state for one durable workspace branch.

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
CREATING	class attribute	'creating'
OPEN	class attribute	'open'
PUBLICATION_INTENT	class attribute	'publication_intent'
PUBLICATION_PROGRESS	class attribute	'publication_progress'
COMMITTED	class attribute	'committed'
ROLLBACK_INTENT	class attribute	'rollback_intent'
ROLLED_BACK	class attribute	'rolled_back'
CONFLICTED	class attribute	'conflicted'
FAILED	class attribute	'failed'
EXPIRED	class attribute	'expired'
AMBIGUOUS	class attribute	'ambiguous'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchEvidence

from cayu.workspaces import WorkspaceBranchEvidence

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
branch_id	str | None	None
source	WorkspaceIdentity	required
baseline_revision	str | None	None
outcome	WorkspaceBranchOutcomeStatus	required
change_set_digest	str | None	None
affected_path_sha256	tuple[str, ...]	()
detail_code	str | None	None

validate_optional_text (method)

WorkspaceBranchEvidence.validate_optional_text(value: str | None, info) -> str | None

validate_path_digests (method)

WorkspaceBranchEvidence.validate_path_digests(value: tuple[str, ...]) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

WorkspaceBranchFencedError

from cayu.workspaces import WorkspaceBranchFencedError

Workspace reuse is unsafe after publication rollback failed.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

WorkspaceBranchLifecycleInspection

from cayu.workspaces import WorkspaceBranchLifecycleInspection

How callers can inspect lifecycle without exposing branch contents.

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
UNSUPPORTED	class attribute	'unsupported'
ATTACHED	class attribute	'attached'
RECOVERABLE_BY_ID	class attribute	'recoverable_by_id'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchLifecycleStatus

from cayu.workspaces import WorkspaceBranchLifecycleStatus

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
ACTIVE	class attribute	'active'
PUBLISHING	class attribute	'publishing'
ROLLING_BACK	class attribute	'rolling_back'
COMMITTED	class attribute	'committed'
ROLLED_BACK	class attribute	'rolled_back'
FENCED	class attribute	'fenced'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchLifecycleSummary

from cayu.workspaces import WorkspaceBranchLifecycleSummary

Bounded, content-free lifecycle states for branches attached here.

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
attached_count	StrictInt	Field(ge=0, le=MAX_ATTACHED_WORKSPACE_BRANCH_LIFECYCLES)
statuses	tuple[WorkspaceBranchLifecycleStatus, ...]	Field(max_length=MAX_ATTACHED_WORKSPACE_BRANCH_LIFECYCLES)
truncated	StrictBool	False

validate_attached_count (method)

WorkspaceBranchLifecycleSummary.validate_attached_count() -> WorkspaceBranchLifecycleSummary

Release source · Runtime guarantees · Capability guides

WorkspaceBranchLimits

from cayu.workspaces import WorkspaceBranchLimits

Hard limits for one local workspace branch.

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
lifetime_ms	StrictInt	Field(default=15 * 60 * 1000, ge=1, le=24 * 60 * 60 * 1000)
max_paths	StrictInt	Field(default=4096, ge=1, le=100000)
max_files	StrictInt	Field(default=4096, ge=1, le=100000)
max_path_bytes	StrictInt	Field(default=4096, ge=1, le=65536)
max_file_bytes	StrictInt	Field(default=8 * 1024 * 1024, ge=1, le=64 * 1024 * 1024)
max_baseline_bytes	StrictInt	Field(default=64 * 1024 * 1024, ge=1, le=1024 * 1024 * 1024)
max_overlay_bytes	StrictInt	Field(default=64 * 1024 * 1024, ge=1, le=1024 * 1024 * 1024)
max_changed_paths	StrictInt	Field(default=4096, ge=1, le=100000)
max_publication_attempts	StrictInt	Field(default=64, ge=1, le=4096)
max_evidence_bytes	StrictInt	Field(default=1024 * 1024, ge=1024, le=16 * 1024 * 1024)
max_active_branches	StrictInt	Field(default=16, ge=1, le=256)

Release source · Runtime guarantees · Capability guides

WorkspaceBranchOperationConflict

from cayu.workspaces import WorkspaceBranchOperationConflict

A stable branch operation identity was reused with different authority.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

WorkspaceBranchOutcomeStatus

from cayu.workspaces import WorkspaceBranchOutcomeStatus

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
CREATED	class attribute	'created'
COMMITTED	class attribute	'committed'
ROLLED_BACK	class attribute	'rolled_back'
CONFLICTED	class attribute	'conflicted'
UNSUPPORTED	class attribute	'unsupported'
RESOURCE_EXHAUSTED	class attribute	'resource_exhausted'
FAILED	class attribute	'failed'
AMBIGUOUS	class attribute	'ambiguous'
EXPIRED	class attribute	'expired'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchPublicationError

from cayu.workspaces import WorkspaceBranchPublicationError

Publication failed after mutation began; source rollback was attempted.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

WorkspaceBranchPublicationRequest

from cayu.workspaces import WorkspaceBranchPublicationRequest

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
branch_id	str	required
baseline_revision	str	required
change_set_digest	str	required
idempotency_key	str | None	Field(default=None, max_length=512)
expected_run_epoch	StrictInt | None	Field(default=None, ge=0)
binding_generation	str | None	Field(default=None, max_length=512)

validate_text (method)

WorkspaceBranchPublicationRequest.validate_text(value: str | None, info) -> str | None

validate_durable_authority (method)

WorkspaceBranchPublicationRequest.validate_durable_authority() -> WorkspaceBranchPublicationRequest

Release source · Runtime guarantees · Capability guides

WorkspaceBranchPublicationResult

from cayu.workspaces import WorkspaceBranchPublicationResult

Decorators: @dataclass(frozen=True).

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
status	WorkspaceBranchOutcomeStatus	required
evidence	WorkspaceBranchEvidence	required
conflicts	tuple[WorkspaceBranchConflict, ...]	()

Release source · Runtime guarantees · Capability guides

WorkspaceBranchPublicationStrength

from cayu.workspaces import WorkspaceBranchPublicationStrength

Truthful multi-path publication strength advertised by an adapter.

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
UNSUPPORTED	class attribute	'unsupported'
COOPERATIVE_ATOMIC	class attribute	'cooperative_atomic'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRecoveryRequest

from cayu.workspaces import WorkspaceBranchRecoveryRequest

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
branch_id	str	Field(max_length=256)
session_id	str	Field(max_length=512)
expected_run_epoch	StrictInt	Field(ge=0)
binding_generation	str	Field(max_length=512)
binding_identity	str	Field(max_length=512)
recovery_id	str	Field(max_length=512)

validate_identity (method)

WorkspaceBranchRecoveryRequest.validate_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRecoveryResult

from cayu.workspaces import WorkspaceBranchRecoveryResult

Decorators: @dataclass(frozen=True).

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
state	WorkspaceBranchDurableState	required
evidence	WorkspaceBranchEvidence	required
branch	WorkspaceBranch | None	None
publication	WorkspaceBranchPublicationResult | None	None
rollback	WorkspaceBranchRollbackResult | None	None

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRecoveryStrength

from cayu.workspaces import WorkspaceBranchRecoveryStrength

How far an adapter can reconstruct a branch after owner loss.

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
UNSUPPORTED	class attribute	'unsupported'
PROCESS_LOCAL	class attribute	'process_local'
DURABLE	class attribute	'durable'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRequest

from cayu.workspaces import WorkspaceBranchRequest

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
baseline	WorkspaceRevisionObservation	required
limits	WorkspaceBranchLimits	Field(default_factory=WorkspaceBranchLimits)
branch_id	str | None	Field(default=None, max_length=256)
idempotency_key	str | None	Field(default=None, max_length=512)
authority	WorkspaceBranchAuthority | None	None

validate_optional_identity (method)

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

validate_baseline (method)

WorkspaceBranchRequest.validate_baseline() -> WorkspaceBranchRequest

Release source · Runtime guarantees · Capability guides

WorkspaceBranchResourceExhaustedError

from cayu.workspaces import WorkspaceBranchResourceExhaustedError

Bases: RuntimeError.

init (method)

WorkspaceBranchResourceExhaustedError.__init__(detail_code: str) -> None

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRetentionStrength

from cayu.workspaces import WorkspaceBranchRetentionStrength

Where branch contents and lifecycle evidence are retained.

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
UNSUPPORTED	class attribute	'unsupported'
PROCESS_LOCAL	class attribute	'process_local'
DURABLE	class attribute	'durable'

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRollbackRequest

from cayu.workspaces import WorkspaceBranchRollbackRequest

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
branch_id	str	Field(max_length=256)
idempotency_key	str	Field(max_length=512)
expected_run_epoch	StrictInt	Field(ge=0)
binding_generation	str	Field(max_length=512)
reason	Literal['explicit', 'expired']	'explicit'

validate_identity (method)

WorkspaceBranchRollbackRequest.validate_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

WorkspaceBranchRollbackResult

from cayu.workspaces import WorkspaceBranchRollbackResult

Decorators: @dataclass(frozen=True).

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
status	WorkspaceBranchOutcomeStatus	required
evidence	WorkspaceBranchEvidence	required

Release source · Runtime guarantees · Capability guides

WorkspaceBranchStore

from cayu.workspaces import WorkspaceBranchStore

Narrow durable journal required by local workspace branches.

Decorators: @runtime_checkable.

Bases: Protocol.

durability (property)

WorkspaceBranchStore.durability() -> WorkspaceBranchStoreDurability

Declare whether journal records survive loss of the owning process.

load_workspace_branch_record (method)

async WorkspaceBranchStore.load_workspace_branch_record(session_id: str, storage_key: str) -> dict[str, Any] | None

Load one branch-owned durable record.

publish_workspace_branch_record (method)

async WorkspaceBranchStore.publish_workspace_branch_record(session_id: str, storage_key: str, *, record_transform: WorkspaceBranchRecordTransform, expected_run_epoch: int, commit_guard: Callable[[], None] | None=None) -> None

Atomically transform one record, optionally beside an owned guarded mutation.

A supplied guard may perform bounded synchronous filesystem work. The implementation must not abandon it on cancellation or run it on an asyncio event-loop thread.

Release source · Runtime guarantees · Capability guides

WorkspaceBranchStoreDurability

from cayu.workspaces import WorkspaceBranchStoreDurability

Persistence evidence declared by a workspace branch journal.

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
DEVELOPMENT	class attribute	'development'
DURABLE	class attribute	'durable'
READ_ONLY	class attribute	'read_only'
UNVERIFIED	class attribute	'unverified'

Release source · Runtime guarantees · Capability guides