Skip to content

cayu.workspaces.checkpoints

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.

capture_workspace_checkpoint

Section titled “capture_workspace_checkpoint”
from cayu import capture_workspace_checkpoint

Capture, pin, and independently verify a complete regular-file revision.

async capture_workspace_checkpoint(workspace: Workspace, store: ArtifactStore, *, policy: WorkspaceCheckpointPolicy, environment_name: str, owner: str, isolation: Callable[[], WorkspaceWriterIsolationEvidence]) -> tuple[str, WorkspaceCheckpointManifest]

Release source · Runtime guarantees · Capability guides

load_workspace_checkpoint

Section titled “load_workspace_checkpoint”
from cayu import load_workspace_checkpoint
async load_workspace_checkpoint(store: ArtifactStore, artifact_id: str, *, policy: WorkspaceCheckpointPolicy, expected_manifest_sha256: str) -> WorkspaceCheckpointManifest

Release source · Runtime guarantees · Capability guides

pin_workspace_checkpoint

Section titled “pin_workspace_checkpoint”
from cayu import pin_workspace_checkpoint

Retain a revision for a session, task, snapshot, or descendant owner.

async pin_workspace_checkpoint(store: ArtifactStore, artifact_id: str, *, owner: str, policy: WorkspaceCheckpointPolicy, expected_manifest_sha256: str) -> None

Release source · Runtime guarantees · Capability guides

release_workspace_checkpoint

Section titled “release_workspace_checkpoint”
from cayu import release_workspace_checkpoint

Release a retired owner’s revision. Other owners continue to block GC.

async release_workspace_checkpoint(store: ArtifactStore, artifact_id: str, *, owner: str, policy: WorkspaceCheckpointPolicy, expected_manifest_sha256: str) -> None

Release source · Runtime guarantees · Capability guides

restore_workspace_checkpoint

Section titled “restore_workspace_checkpoint”
from cayu import restore_workspace_checkpoint

Reconstruct an owned projection without rerunning any tool effects.

Partial restoration is idempotent. The caller must retain its recovery fence and cannot expose the environment until verification succeeds.

async restore_workspace_checkpoint(workspace: Workspace, store: ArtifactStore, manifest: WorkspaceCheckpointManifest, *, policy: WorkspaceCheckpointPolicy, isolation: Callable[[], WorkspaceWriterIsolationEvidence]) -> None

Release source · Runtime guarantees · Capability guides

WorkspaceCheckpointError

Section titled “WorkspaceCheckpointError”
from cayu import WorkspaceCheckpointError

No subsequent execution is safe until this checkpoint failure is resolved.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

WorkspaceCheckpointManifest

Section titled “WorkspaceCheckpointManifest”
from cayu import WorkspaceCheckpointManifest

Bases: BaseModel.

Fields and attributes

Section titled “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
schema_version Literal[1] 1
revision str Field(pattern='^[0-9a-f]{64}$')
files tuple[WorkspaceCheckpointFile, ...] required

validate_limits (method)

Section titled “validate_limits (method)”
WorkspaceCheckpointManifest.validate_limits(policy: WorkspaceCheckpointPolicy) -> None

Release source · Runtime guarantees · Capability guides

WorkspaceCheckpointPolicy

Section titled “WorkspaceCheckpointPolicy”
from cayu import WorkspaceCheckpointPolicy

Enable durable revisions for an exclusively owned workspace.

Limits cover the complete workspace projection exposed by its adapter. Symlinks and special files fail closed; excluded paths are not checkpointed.

Bases: BaseModel.

Fields and attributes

Section titled “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
timeout_seconds StrictInt Field(default=120, ge=1, le=3600)
max_paths StrictInt Field(default=10000, ge=1, le=100000)
max_file_bytes StrictInt Field(default=64 * 1024 * 1024, ge=1, le=256 * 1024 * 1024)
max_total_bytes StrictInt Field(default=256 * 1024 * 1024, ge=1, le=4 * 1024 ** 3)
max_manifest_bytes StrictInt Field(default=4 * 1024 * 1024, ge=1024, le=32 * 1024 * 1024)
allocation_replacement Literal['never', 'restore'] 'never'

Release source · Runtime guarantees · Capability guides