cayu.workspaces.revisions

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.

`compare_workspace_revisions`

from cayu.workspaces import compare_workspace_revisions

Compare two complete observations without interpreting revisions as snapshots.

compare_workspace_revisions(before: WorkspaceRevisionObservation, after: WorkspaceRevisionObservation) -> WorkspaceRevisionDelta

Release source · Runtime guarantees · Capability guides

`WorkspaceDirectMutationReconciliation`

from cayu.workspaces import WorkspaceDirectMutationReconciliation

Agreement between direct workspace operations and observed revisions.

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
`NOT_OBSERVED`	`class attribute`	`'not_observed'`
`CONSISTENT`	`class attribute`	`'consistent'`
`INCOMPLETE`	`class attribute`	`'incomplete'`
`CONTRADICTORY`	`class attribute`	`'contradictory'`
`TRUNCATED`	`class attribute`	`'truncated'`

Release source · Runtime guarantees · Capability guides

`WorkspaceForkLineage`

from cayu.workspaces import WorkspaceForkLineage

Bounded workspace lineage evidence for a transcript/session fork.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`status`	`WorkspaceForkLineageStatus`	`required`
`source_workspace_revision`	`str \| None`	`None`
`detail_code`	`str`	`Field(max_length=_WORKSPACE_ATTRIBUTION_TEXT_MAX_CHARS)`

validate_optional_revision (method)

WorkspaceForkLineage.validate_optional_revision(value: str | None) -> str | None

validate_lineage_detail (method)

WorkspaceForkLineage.validate_lineage_detail(value: str) -> str

validate_lineage_shape (method)

WorkspaceForkLineage.validate_lineage_shape() -> WorkspaceForkLineage

Release source · Runtime guarantees · Capability guides

`WorkspaceForkLineageStatus`

from cayu.workspaces import WorkspaceForkLineageStatus

Relationship between source and child workspaces at session fork.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DERIVED`	`class attribute`	`'derived'`
`SHARED_OR_AMBIGUOUS`	`class attribute`	`'shared_or_ambiguous'`
`UNPROVEN`	`class attribute`	`'unproven'`

Release source · Runtime guarantees · Capability guides

`WorkspaceIdentity`

from cayu.workspaces import WorkspaceIdentity

Stable workspace identity plus the adapter that observed it.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`workspace_id`	`str`	`required`
`observer`	`str`	`required`

validate_identity (method)

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

Release source · Runtime guarantees · Capability guides

`WorkspaceMutationAttribution`

from cayu.workspaces import WorkspaceMutationAttribution

Conservative attribution attached to an observed workspace delta.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`confidence`	`WorkspaceMutationAttributionConfidence`	`required`
`writer_isolation`	`WorkspaceWriterIsolationStatus`	`required`
`overlap_detected`	`StrictBool`	`False`
`direct_reconciliation`	`WorkspaceDirectMutationReconciliation`	`WorkspaceDirectMutationReconciliation.NOT_OBSERVED`
`detail_code`	`str`	`Field(max_length=_WORKSPACE_ATTRIBUTION_TEXT_MAX_CHARS)`

validate_detail_code (method)

WorkspaceMutationAttribution.validate_detail_code(value: str) -> str

validate_attribution_shape (method)

WorkspaceMutationAttribution.validate_attribution_shape() -> WorkspaceMutationAttribution

Release source · Runtime guarantees · Capability guides

`WorkspaceMutationAttributionConfidence`

from cayu.workspaces import WorkspaceMutationAttributionConfidence

How confidently an observed workspace change can be assigned.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`EXCLUSIVE_TOOL`	`class attribute`	`'exclusive_tool'`
`CONCURRENT_AMBIGUITY`	`class attribute`	`'concurrent_ambiguity'`
`EXTERNAL_OR_UNKNOWN`	`class attribute`	`'external_or_unknown'`
`UNATTRIBUTED_FINALIZATION_CHANGE`	`class attribute`	`'unattributed_finalization_change'`

Release source · Runtime guarantees · Capability guides

`WorkspaceRevisionDelta`

from cayu.workspaces import WorkspaceRevisionDelta

Bounded observed change between two revisions; it does not imply causation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`identity`	`WorkspaceIdentity`	`required`
`status`	`WorkspaceRevisionDeltaStatus`	`required`
`before_revision`	`str \| None`	`None`
`after_revision`	`str \| None`	`None`
`paths`	`tuple[WorkspacePathRevisionDelta, ...]`	`()`
`total_paths`	`StrictInt`	`Field(default=0, ge=0)`
`head_changed`	`StrictBool`	`False`
`branch_changed`	`StrictBool`	`False`
`detail_code`	`str \| None`	`None`

validate_optional_text (method)

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

validate_delta_shape (method)

WorkspaceRevisionDelta.validate_delta_shape() -> WorkspaceRevisionDelta

Release source · Runtime guarantees · Capability guides

`WorkspaceRevisionDeltaStatus`

from cayu.workspaces import WorkspaceRevisionDeltaStatus

Outcome of comparing two workspace observations.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`CHANGED`	`class attribute`	`'changed'`
`NO_CHANGE`	`class attribute`	`'no_change'`
`UNSUPPORTED`	`class attribute`	`'unsupported'`
`FAILED`	`class attribute`	`'failed'`
`INCOMPLETE`	`class attribute`	`'incomplete'`
`TRUNCATED`	`class attribute`	`'truncated'`

Release source · Runtime guarantees · Capability guides

`WorkspaceRevisionObservation`

from cayu.workspaces import WorkspaceRevisionObservation

Bounded evidence for one observed workspace state.

revision is an observation digest, not an optimistic file token and not a restorable filesystem snapshot.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`identity`	`WorkspaceIdentity`	`required`
`status`	`WorkspaceRevisionObservationStatus`	`required`
`revision`	`str \| None`	`None`
`head_revision`	`str \| None`	`None`
`branch`	`str \| None`	`None`
`path_scope`	`Literal['complete', 'changed']`	`'complete'`
`paths`	`tuple[WorkspacePathRevision, ...]`	`()`
`total_paths`	`StrictInt`	`Field(default=0, ge=0)`
`detail_code`	`str \| None`	`None`

validate_optional_text (method)

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

validate_observation_shape (method)

WorkspaceRevisionObservation.validate_observation_shape() -> WorkspaceRevisionObservation

Release source · Runtime guarantees · Capability guides

`WorkspaceRevisionObservationLimits`

from cayu.workspaces import WorkspaceRevisionObservationLimits

Hard collection limits for workspace revision evidence.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`max_paths`	`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_total_file_bytes`	`StrictInt`	`Field(default=64 * 1024 * 1024, ge=1, le=1024 * 1024 * 1024)`
`max_manifest_bytes`	`StrictInt`	`Field(default=1024 * 1024, ge=1024, le=16 * 1024 * 1024)`

Release source · Runtime guarantees · Capability guides

`WorkspaceRevisionObservationStatus`

from cayu.workspaces import WorkspaceRevisionObservationStatus

Outcome of one optional workspace revision observation.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`SUPPORTED`	`class attribute`	`'supported'`
`UNSUPPORTED`	`class attribute`	`'unsupported'`
`FAILED`	`class attribute`	`'failed'`
`INCOMPLETE`	`class attribute`	`'incomplete'`
`TRUNCATED`	`class attribute`	`'truncated'`

Release source · Runtime guarantees · Capability guides

`WorkspaceWriterIsolationEvidence`

from cayu.workspaces import WorkspaceWriterIsolationEvidence

Bounded adapter evidence for workspace-writer isolation.

EXCLUSIVE is an adapter contract, not an inference from serialized tool execution. The same non-secret generation must be observed at both ends of a mutation window before the runtime may use it for exact attribution.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`status`	`WorkspaceWriterIsolationStatus`	`WorkspaceWriterIsolationStatus.UNKNOWN`
`mechanism`	`str \| None`	`Field(default=None, max_length=_WORKSPACE_ATTRIBUTION_TEXT_MAX_CHARS)`
`generation`	`str \| None`	`Field(default=None, max_length=_WORKSPACE_ATTRIBUTION_TEXT_MAX_CHARS)`
`detail_code`	`str \| None`	`Field(default='writer_isolation_unavailable', max_length=_WORKSPACE_ATTRIBUTION_TEXT_MAX_CHARS)`

validate_optional_text (method)

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

validate_evidence_shape (method)

WorkspaceWriterIsolationEvidence.validate_evidence_shape() -> WorkspaceWriterIsolationEvidence

Release source · Runtime guarantees · Capability guides

`WorkspaceWriterIsolationStatus`

from cayu.workspaces import WorkspaceWriterIsolationStatus

Adapter evidence about writers outside one Cayu mutation window.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`EXCLUSIVE`	`class attribute`	`'exclusive'`
`SHARED`	`class attribute`	`'shared'`
`UNKNOWN`	`class attribute`	`'unknown'`

Release source · Runtime guarantees · Capability guides