cayu.runtime.session_message_lifecycle

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.

`SessionMessageAccessContext`

from cayu import SessionMessageAccessContext

Verified identity from trusted SDK code or HTTP authentication, not JSON metadata.

Bases: _MessageLifecycleModel.

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
`subject`	`StrictStr`	`Field(min_length=1, max_length=512)`
`tenant`	`StrictStr \| None`	`Field(default=None, min_length=1, max_length=512)`

validate_identity (method)

SessionMessageAccessContext.validate_identity(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`SessionMessageAccessDenied`

from cayu import SessionMessageAccessDenied

Bases: PermissionError.

init (method)

SessionMessageAccessDenied.__init__() -> None

Release source · Runtime guarantees · Capability guides

`SessionMessageAccessPolicy`

from cayu import SessionMessageAccessPolicy

Application-owned, side-effect-free authorization using trusted ownership data.

Authentication and matching tenant strings are not ownership evidence. The implementation must resolve its own subject/tenant/session permission map. Source access is requested independently from target admission or inspection.

Bases: ABC.

authorize (method)

SessionMessageAccessPolicy.authorize(context: SessionMessageAccessContext, *, session_id: str, session_instance_id: str, action: Literal['inspect', 'enqueue', 'source', 'withdraw', 'quarantine']) -> bool

Release source · Runtime guarantees · Capability guides

`SessionMessageActionRequest`

from cayu import SessionMessageActionRequest

Compare-and-set withdrawal/quarantine of an inspected queue record.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`session_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`session_instance_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`queue_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`idempotency_key`	`StrictStr`	`Field(min_length=1, max_length=256)`
`expected_revision`	`StrictStr`	`Field(pattern='^[0-9a-f]{64}$')`
`action`	`Literal['withdraw', 'quarantine']`	`required`
`requested_by`	`ResolutionActor \| None`	`None`

validate_identity (method)

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

copy_actor (method)

SessionMessageActionRequest.copy_actor(value)

Release source · Runtime guarantees · Capability guides

`SessionMessageConditions`

from cayu import SessionMessageConditions

Optional provenance and delivery constraints; never ordinary metadata.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`source`	`SessionMessageSource \| None`	`None`
`target`	`SessionMessageTarget \| None`	`None`
`expires_at`	`datetime \| None`	`None`

copy_source (method)

SessionMessageConditions.copy_source(value)

copy_target (method)

SessionMessageConditions.copy_target(value)

validate_expiry (method)

SessionMessageConditions.validate_expiry(value: datetime | None) -> datetime | None

Release source · Runtime guarantees · Capability guides

`SessionMessageConflict`

from cayu import SessionMessageConflict

Bases: ValueError.

init (method)

SessionMessageConflict.__init__() -> None

Release source · Runtime guarantees · Capability guides

`SessionMessageCursor`

from cayu import SessionMessageCursor

Incarnation-bound position within a fixed admission high-water mark.

Priority is NEXT_TURN (0), ON_IDLE (1), then unreadable modes (2). The cursor is pagination input, never application access authority.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`session_instance_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`through_ordering_key`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`after_priority`	`StrictInt`	`Field(ge=0, le=2)`
`after_ordering_key`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`

validate_identity (method)

SessionMessageCursor.validate_identity(value: str) -> str

validate_position (method)

SessionMessageCursor.validate_position() -> SessionMessageCursor

Release source · Runtime guarantees · Capability guides

`SessionMessageQuery`

from cayu import SessionMessageQuery

Bounded delivery-priority inspection, including terminal and unreadable rows.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`session_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`cursor`	`SessionMessageCursor \| None`	`None`
`limit`	`StrictInt`	`Field(default=50, ge=1, le=100)`

copy_cursor (method)

SessionMessageQuery.copy_cursor(value)

validate_identity (method)

SessionMessageQuery.validate_identity(value: str) -> str

Release source · Runtime guarantees · Capability guides

`SessionMessageQueueStatus`

from cayu import SessionMessageQueueStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`QUEUED`	`class attribute`	`'queued'`
`DELIVERED`	`class attribute`	`'delivered'`
`WITHDRAWN`	`class attribute`	`'withdrawn'`
`QUARANTINED`	`class attribute`	`'quarantined'`
`STALE`	`class attribute`	`'stale'`
`EXPIRED`	`class attribute`	`'expired'`

Release source · Runtime guarantees · Capability guides

`SessionMessageSource`

from cayu import SessionMessageSource

Exact source observation, checked by the store before first acceptance.

Source observations are historical after admission: identical retries do not reinterpret them against a newer source. A copied observation is not access authority; the application must independently authorize the source session.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`session_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`session_instance_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`run_epoch`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`transcript_cursor`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`transcript_sha256`	`StrictStr \| None`	`Field(default=None, pattern='^[0-9a-f]{64}$')`
`checkpoint_sha256`	`StrictStr \| None`	`Field(default=None, pattern='^[0-9a-f]{64}$')`

validate_identity (method)

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

Release source · Runtime guarantees · Capability guides

`SessionMessageTarget`

from cayu import SessionMessageTarget

Expected target immediately before this message’s transcript append.

The instance prevents deletion/recreation from satisfying an old request. Both epoch and permanent transcript cursor must match exactly. Earlier delivered messages advance that cursor; terminal rejection does not. This definition is independent of the store’s delivery batch size.

Bases: _MessageLifecycleModel.

Fields and attributes

Name	Type	Default
`session_instance_id`	`StrictStr`	`Field(min_length=1, max_length=512)`
`run_epoch`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`transcript_cursor`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`

validate_identity (method)

SessionMessageTarget.validate_identity(value: str) -> str

Release source · Runtime guarantees · Capability guides