cayu.storage.PostgresSessionStore

Part of cayu.storage.postgres. Read the Python API overview and install the required extra.

from cayu.storage import PostgresSessionStore

Postgres-backed session store for shared durable runtime state.

Decorators: @model_store_surface('sessions').

Bases: PostgresExternalWaitMixin, PostgresSessionExecutionMixin, PostgresContextSelectionFenceMixin, PostgresCreationFenceMixin, _PostgresStoreBase, SessionStore.

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
supports_session_execution	class attribute	False
service_durability	RuntimeStoreDurability	RuntimeStoreDurability.DURABLE

inspect_session_execution (method)

async PostgresSessionStore.inspect_session_execution(session_id: str) -> SessionExecutionState

Read observational liveness; custom stores without leases return unknown.

read_context_view_selection_decision (method)

async PostgresSessionStore.read_context_view_selection_decision(request)

Exact receiving readback, not current disclosure or ownership authority.

list_pending_session_creations (method)

async PostgresSessionStore.list_pending_session_creations(owner, *, cursor=None, limit=32)

read_session_creation_decision (method)

async PostgresSessionStore.read_session_creation_decision(target)

init (method)

PostgresSessionStore.__init__(conninfo: str | None=None, *, pool: AsyncConnectionPool | None=None, min_size: int=1, max_size: int=8, schema_mode: schema.SchemaMode=schema.SchemaMode.VALIDATE, read_only: bool=False, public_authority_alias_codec: PublicAuthorityAliasCodec | None=None, migration_reset_empty_recall_state: bool=False, migration_expected_input_state: schema.SchemaState | None=None, migration_operation_sha256: str | None=None, migration_receipt_json: str | None=None, clock: Callable[[], datetime] | None=None) -> None

ensure_schema (method)

async PostgresSessionStore.ensure_schema() -> None

Open the pool and reconcile the schema now (per schema_mode).

Normally reconciliation happens lazily on first use; the cayu storage CLI calls this to run a migrate (or validate) as an explicit step.

close (method)

async PostgresSessionStore.close() -> None

create_participant_owned_session (method)

async PostgresSessionStore.create_participant_owned_session(creation_request, *, resolved_request, identity, binding_factory, recipient_provenance=None, recipient_selection=None, creation_target=None, recipient_receipt_validator=None)

load_participant_session_binding (method)

async PostgresSessionStore.load_participant_session_binding(session_id)

load_participant_session_creation_receipt (method)

async PostgresSessionStore.load_participant_session_creation_receipt(session_id)

lookup_participant_session_creation (method)

async PostgresSessionStore.lookup_participant_session_creation(creation_request)

capture_context_view_publication_source (method)

async PostgresSessionStore.capture_context_view_publication_source(session_id)

capture_recipient_continuation (method)

async PostgresSessionStore.capture_recipient_continuation(session_id: str) -> RecipientContinuationSelection

Select exact identity without acquiring a writer or execution authority.

Wrappers must independently qualify this coherent native read. Inheriting an implementation is not evidence that wrapper-specific state is covered.

publish_context_view (method)

async PostgresSessionStore.publish_context_view(manifest, *, publication_key)

lookup_context_view_selection (method)

async PostgresSessionStore.lookup_context_view_selection(selection_key)

lookup_context_view_publication (method)

async PostgresSessionStore.lookup_context_view_publication(publication_key)

select_context_view (method)

async PostgresSessionStore.select_context_view(request)

read_context_view (method)

async PostgresSessionStore.read_context_view(view_id: str, *, source_session_id: str)

transition_context_view_ownership (method)

async PostgresSessionStore.transition_context_view_ownership(request)

validate_context_view_source_closure (method)

async PostgresSessionStore.validate_context_view_source_closure(session_id: str) -> None

validate_context_view_compaction (method)

async PostgresSessionStore.validate_context_view_compaction(session_id: str, expected_transcript_cursor: int) -> None

read_context_view_lifecycle_events (method)

async PostgresSessionStore.read_context_view_lifecycle_events(view_id: str, *, limit: int=256, owner_participant=None)

durable_state_paths (method)

PostgresSessionStore.durable_state_paths() -> tuple[Path, ...]

Return local files that own this store’s durable state.

In-memory and remote stores return no paths. Filesystem-confined features must fail closed when the store cannot provide this evidence; custom local stores can opt in by overriding this method.

public_authority_alias_codec (property)

PostgresSessionStore.public_authority_alias_codec() -> PublicAuthorityAliasCodec | None

Return the immutable codec configured for durable alias registration.

register_public_authority_alias (method)

async PostgresSessionStore.register_public_authority_alias(public_alias: str, *, field_name: str, private_value: str, scope_session_id: str | None=None) -> None

Atomically register one codec-authenticated public authority alias.

resolve_public_authority_alias (method)

async PostgresSessionStore.resolve_public_authority_alias(public_alias: str, *, field_name: str, scope_session_id: str | None=None) -> str | None

Resolve one exact alias through its indexed authority scope.

public_authority_private_value_exists (method)

async PostgresSessionStore.public_authority_private_value_exists(private_value: str, *, field_name: str, scope_session_id: str | None=None) -> bool

issue_targeted_tool_grants (method)

async PostgresSessionStore.issue_targeted_tool_grants(session_id: str, *, expected_run_epoch: int, records: tuple[TargetedToolGrantRecord, ...], events: tuple[Event, ...]) -> TargetedToolGrantIssueResult

list_targeted_tool_grants (method)

async PostgresSessionStore.list_targeted_tool_grants(session_id: str, *, interaction_id: str | None=None, limit: int=TARGETED_TOOL_GRANT_INSPECTION_MAX_RECORDS) -> tuple[TargetedToolGrantRecord, ...]

load_targeted_tool_grant_state (method)

async PostgresSessionStore.load_targeted_tool_grant_state(session_id: str) -> TargetedToolGrantStateSnapshot

bind_targeted_tool_grant_use (method)

async PostgresSessionStore.bind_targeted_tool_grant_use(request: TargetedToolUseRequest, *, observed_at: datetime) -> TargetedToolUseResult

revoke_targeted_tool_grant (method)

async PostgresSessionStore.revoke_targeted_tool_grant(tool_ref: str, *, session_id: str, expected_run_epoch: int, reason: str, revoked_at: datetime) -> TargetedToolGrantRecord | None

reconstruct_targeted_tool_grants (method)

async PostgresSessionStore.reconstruct_targeted_tool_grants(session_id: str, *, expected_run_epoch: int, interaction_id: str, generation_id: str, agent_name: str, task_id: str | None, environment_name: str | None, principal: str | None, tenant: str | None, catalogue_revision: str, descriptors_by_id: Mapping[str, tuple[str, str, str]], capability_ceiling_names: frozenset[str], observed_at: datetime) -> TargetedToolGrantReconstructionResult

create (method)

async PostgresSessionStore.create(request: RunRequest, *, identity: SessionIdentity, interaction_started_event: Event | None=None, interaction_source_messages: list[Message] | None=None, checkpoint_transform: CheckpointTransform | None=None, result_checkpoint_transform: CheckpointTransform | None=None, operation_initializer: SessionOperationInitializer | None=None, participant_binding_factory: Callable[[Session], tuple[Any, Any]] | None=None, participant_request_commitment: str | None=None, participant_provenance=None, recipient_selection=None, creation_target=None, recipient_receipt_validator=None) -> Session

create_fork (method)

async PostgresSessionStore.create_fork(*, source_session_id: str, fork: Session, source_statuses: set[SessionStatus], transcript_cursor: int | None, checkpoint_transform: CheckpointTransform | None, system_prompt_replacement: ForkSystemPromptReplacement | None=None, expected_source_run_epoch: int, operation_initializer: SessionOperationInitializer | None=None) -> Session

create_fork_with_transcript_validation (method)

async PostgresSessionStore.create_fork_with_transcript_validation(*, source_session_id: str, fork: Session, source_statuses: set[SessionStatus], transcript_cursor: int | None, checkpoint_transform: CheckpointTransform | None, system_prompt_replacement: ForkSystemPromptReplacement | None=None, expected_source_run_epoch: int, transcript_validator: ForkTranscriptValidator, operation_initializer: SessionOperationInitializer | None=None) -> Session

create_profiled_fork (method)

async PostgresSessionStore.create_profiled_fork(*, source_session_id: str, fork: Session, source_statuses: set[SessionStatus], transcript_cursor: int | None, checkpoint_transform: CheckpointTransform | None, system_prompt_replacement: ForkSystemPromptReplacement | None=None, expected_source_run_epoch: int, relationship: SessionForkProfileRelationship, events: list[Event], transcript_validator: ForkTranscriptValidator | None=None, checkpoint_authority_decoder: ForkCheckpointAuthorityDecoder | None=None, operation_initializer: SessionOperationInitializer | None=None) -> ProfiledSessionForkResult

load (method)

async PostgresSessionStore.load(session_id: str) -> Session | None

load_state (method)

async PostgresSessionStore.load_state(session_id: str) -> SessionStateSnapshot | None

load_invocation_snapshot (method)

async PostgresSessionStore.load_invocation_snapshot(session_id: str) -> SessionInvocationSnapshot | None

inspect_identity (method)

async PostgresSessionStore.inspect_identity(session_id: str) -> SessionInspectionIdentity

update_status (method)

async PostgresSessionStore.update_status(session_id: str, status: SessionStatus) -> Session

transition_status (method)

async PostgresSessionStore.transition_status(session_id: str, *, from_statuses: set[SessionStatus], to_status: SessionStatus) -> Session

transition_status_and_checkpoint (method)

async PostgresSessionStore.transition_status_and_checkpoint(session_id: str, *, from_statuses: set[SessionStatus], to_status: SessionStatus, checkpoint_transform: CheckpointTransform | None=None, store_time_checkpoint_transform: StoreTimeCheckpointTransform | None=None, result_checkpoint_transform: CheckpointTransform | None=None, interaction_started_event: Event | None=None, interaction_source_messages: list[Message] | None=None, continued_interaction_id: str | None=None, defer_interaction_source: bool=False, model_transition: SessionModelTransition | None=None, execution_profile: ExecutionProfileIdentity | None=None, execution_profile_decision: ExecutionProfileDecision | None=None, adopted_runtime_identity: SessionRuntimeIdentity | None=None, tool_capability_ceiling: ToolCapabilityCeiling | None=None, expected_latest_interaction_event_id: str | None=None, require_no_active_model_completion_dispatch: bool=False, temporary_service_admission: TemporaryServiceAdmission | None=None) -> Session

admit_execution_profile_resume (method)

async PostgresSessionStore.admit_execution_profile_resume(session_id: str, *, from_statuses: set[SessionStatus], to_status: SessionStatus, checkpoint_transform: CheckpointTransform | None=None, store_time_checkpoint_transform: StoreTimeCheckpointTransform | None=None, result_checkpoint_transform: CheckpointTransform | None=None, execution_profile: ExecutionProfileIdentity, tool_capability_ceiling: ToolCapabilityCeiling | None=None, execution_profile_decision: ExecutionProfileDecision | None=None, adopted_runtime_identity: SessionRuntimeIdentity | None=None, interaction_started_event: Event | None=None, interaction_source_messages: list[Message] | None=None, continued_interaction_id: str | None=None, defer_interaction_source: bool=False, model_transition: SessionModelTransition | None=None, temporary_service_admission: TemporaryServiceAdmission | None=None) -> Session

Atomically compare a profile through the normal resume transition.

admit_session_invocation (method)

async PostgresSessionStore.admit_session_invocation(session_id: str, *, admission: SessionInvocationAdmission) -> Session

Atomically claim one valid profiled invocation and its interaction.

apply_invocation_lifecycle_command (method)

async PostgresSessionStore.apply_invocation_lifecycle_command(command: object) -> object

Apply one command only after authenticating the store protocol.

settle_session_invocation (method)

async PostgresSessionStore.settle_session_invocation(command: Any) -> InteractionTransitionResult

release_session_invocation (method)

async PostgresSessionStore.release_session_invocation(command: Any) -> Any

reject_execution_profile_resume (method)

async PostgresSessionStore.reject_execution_profile_resume(session_id: str, *, expected_session_instance_id: str | None=None, expected_statuses: set[SessionStatus], expected_run_epoch: int, expected_profile: ExecutionProfileIdentity, candidate_profile: ExecutionProfileIdentity, event: Event, decision: ExecutionProfileDecision | None=None, expected_active_invocation_profile_authority: CheckpointValueAuthority | None=None) -> ExecutionProfileRejectionResult

reject_active_invocation_execution_profile (method)

async PostgresSessionStore.reject_active_invocation_execution_profile(session_id: str, *, expected_session_instance_id: str | None=None, expected_statuses: set[SessionStatus], expected_run_epoch: int, expected_active_invocation_profile: ActiveInvocationExecutionProfile, candidate_profile: ExecutionProfileIdentity, event: Event, decision: ExecutionProfileDecision | None=None) -> ExecutionProfileRejectionResult

Atomically compare checkpoint authority and reject changed continuation.

transition_status_if_no_queued_messages (method)

async PostgresSessionStore.transition_status_if_no_queued_messages(session_id: str, *, from_statuses: set[SessionStatus], to_status: SessionStatus, checkpoint_mutation: dict[str, Any] | None=None) -> Session

publish_interaction_transition (method)

async PostgresSessionStore.publish_interaction_transition(session_id: str, *, event: Event, from_statuses: set[SessionStatus], to_status: SessionStatus, only_if_no_queued_messages: bool=False, model_completion_stage_settlement: ModelCompletionStageSettlementRequest | None=None, checkpoint_mutation: dict[str, Any] | None=None, terminal_event: Event | None=None, terminal_decision: InvocationTerminalDecision | None=None, expected_session_instance_id: str | None=None, expected_active_invocation_profile: ActiveInvocationExecutionProfile | None=None, expected_invocation_authority_state: Literal['active', 'released']='active', expected_recovery_claim_id: str | None=None, terminalization_only: bool=False, terminalization_plan_ownership: Any=None) -> InteractionTransitionResult

load_interaction_transition_receipt (method)

async PostgresSessionStore.load_interaction_transition_receipt(session_id: str, *, transition: InteractionTransitionSpec, expected_recovery_claim_id: str | None=None) -> InteractionTransitionReceiptResult | None

load_historical_interaction_settlement (method)

async PostgresSessionStore.load_historical_interaction_settlement(session_id: str, *, expected_session_instance_id: str, expected_event: Event, expected_profile: ExecutionProfileIdentity) -> InteractionTransitionReceiptResult

Read exact prior settlement evidence without granting run authority.

Unlike invocation release lookup, this permits a later current epoch. It cannot release a fence or authorize a historical invocation: callers must separately acquire their own execution or mutation authority.

load_invocation_settlement_transition (method)

async PostgresSessionStore.load_invocation_settlement_transition(session_id: str, *, expected_session_instance_id: str, expected_active_invocation_profile: ActiveInvocationExecutionProfile) -> InteractionTransitionSpec | None

Resolve exact terminal settlement for one active invocation.

Event lookup is bounded and supplies only the receipt identity. The backend authenticates the complete stored receipt and its invocation tuple before returning the transition. Release compares the same receipt again inside its mutation transaction.

fence_stalled_run (method)

async PostgresSessionStore.fence_stalled_run(session_id: str, *, statuses: set[SessionStatus], inactive_for_seconds: int) -> Session | None

reserve_stalled_run_recovery (method)

async PostgresSessionStore.reserve_stalled_run_recovery(session_id: str, *, statuses: set[SessionStatus], inactive_for_seconds: int | None, checkpoint_transform: StoreTimeCheckpointTransform) -> Session | None

fence_run_and_transform_checkpoint (method)

async PostgresSessionStore.fence_run_and_transform_checkpoint(session_id: str, *, statuses: set[SessionStatus], checkpoint_transform: CheckpointTransform, result_checkpoint_transform: CheckpointTransform | None=None) -> Session

release_run_fence (method)

async PostgresSessionStore.release_run_fence(session_id: str) -> None

claim_budget_reservation_identity (method)

async PostgresSessionStore.claim_budget_reservation_identity(*, reservation_id: str, publication_session_id: str, publication_id: str) -> None

append_event (method)

async PostgresSessionStore.append_event(session_id: str, event: Event) -> None

append_events (method)

async PostgresSessionStore.append_events(session_id: str, events: list[Event]) -> None

append_workflow_step_started (method)

async PostgresSessionStore.append_workflow_step_started(session_id: str, event: Event, *, workflow_name: str, attempt_id: str) -> bool

append_tool_effect_conflict (method)

async PostgresSessionStore.append_tool_effect_conflict(request: object) -> Event

load_mcp_manifest_baselines (method)

async PostgresSessionStore.load_mcp_manifest_baselines(history_keys: tuple[str, ...]) -> McpManifestBaselineLoadResult

compare_and_publish_mcp_manifest_checks (method)

async PostgresSessionStore.compare_and_publish_mcp_manifest_checks(session_id: str, *, expected_generations: dict[str, int | None], baseline_updates: dict[str, McpManifestBaseline], events: list[Event]) -> McpManifestPublicationResult

claim_persisted_event_side_effect (method)

async PostgresSessionStore.claim_persisted_event_side_effect(*, session_id: str | None=None, event_id: str | None=None, lease_seconds: float=300.0) -> PersistedEventSideEffectClaim | None

get_persisted_event_side_effect_delivery (method)

async PostgresSessionStore.get_persisted_event_side_effect_delivery(*, session_id: str, event_id: str) -> PersistedEventSideEffectDelivery | None

claim_first_persisted_event_side_effect (method)

async PostgresSessionStore.claim_first_persisted_event_side_effect(expected: PersistedEventSideEffectDelivery) -> PersistedEventSideEffectClaim | None

retire_failed_first_event_delivery (method)

async PostgresSessionStore.retire_failed_first_event_delivery(expected: PersistedEventSideEffectDelivery) -> PersistedEventSideEffectDelivery | None

mark_persisted_event_side_effect_delivered (method)

async PostgresSessionStore.mark_persisted_event_side_effect_delivered(claim: PersistedEventSideEffectClaim) -> PersistedEventSideEffectDelivery

mark_persisted_event_side_effect_failed (method)

async PostgresSessionStore.mark_persisted_event_side_effect_failed(claim: PersistedEventSideEffectClaim, *, error: str, max_attempts: int, retry_delay_seconds: float) -> PersistedEventSideEffectDelivery

list_persisted_event_side_effect_deliveries (method)

async PostgresSessionStore.list_persisted_event_side_effect_deliveries(*, statuses: set[PersistedEventSideEffectStatus] | None=None, claimable_only: bool=False, after_sequence: int | None=None, limit: int=100) -> list[PersistedEventSideEffectDelivery]

get_persisted_event_side_effect_health (method)

async PostgresSessionStore.get_persisted_event_side_effect_health() -> PersistedEventSideEffectHealth

query_persisted_event_side_effect_deliveries (method)

async PostgresSessionStore.query_persisted_event_side_effect_deliveries(query: PersistedEventSideEffectQuery) -> PersistedEventSideEffectPage

defer_persisted_event_side_effect (method)

async PostgresSessionStore.defer_persisted_event_side_effect(claim: PersistedEventSideEffectClaim) -> PersistedEventSideEffectDelivery

renew_persisted_event_side_effect (method)

async PostgresSessionStore.renew_persisted_event_side_effect(claim: PersistedEventSideEffectClaim, *, lease_seconds: float=300.0) -> PersistedEventSideEffectDelivery

enqueue_session_message (method)

async PostgresSessionStore.enqueue_session_message(request: EnqueueSessionMessageRequest, *, expected_authorized_target_instance_id: str | None=None) -> EnqueueSessionMessageResult

append_peer_content (method)

async PostgresSessionStore.append_peer_content(request: PeerContentAppendRequest, *, qualify_target: Callable[[Session], None] | None=None, pending_transcript_cursor: int | None=None) -> PeerContentReceipt

read_peer_content (method)

async PostgresSessionStore.read_peer_content(append_key: PeerAppendKey) -> PeerContentReceipt | None

exclude_peer_content (method)

async PostgresSessionStore.exclude_peer_content(request: PeerContentAppendRequest, *, reason: str) -> PeerContentReceipt

read_peer_content_attempt (method)

async PostgresSessionStore.read_peer_content_attempt(request: PeerContentAppendRequest) -> PeerContentReceipt | None

list_pending_peer_content (method)

async PostgresSessionStore.list_pending_peer_content(*, after_operation_key=None, limit=32)

Trusted receiving-owner discovery, independent of creation settlement.

retry_pending_peer_content (method)

async PostgresSessionStore.retry_pending_peer_content(session_id: str, *, expected_session_instance_id: str, expected_run_epoch: int, expected_transcript_cursor: int, admit=None) -> tuple[PeerContentReceipt, ...]

record_peer_content_exposure (method)

async PostgresSessionStore.record_peer_content_exposure(request: PeerContentExposureRequest) -> PeerContentExposureReceipt

begin_peer_content_exposure (method)

async PostgresSessionStore.begin_peer_content_exposure(request: PeerContentExposureRequest) -> PeerContentExposureReceipt

read_peer_content_exposure (method)

async PostgresSessionStore.read_peer_content_exposure(append_key: PeerAppendKey, exposure_id: str) -> PeerContentExposureReceipt | None

inspect_session_messages (method)

async PostgresSessionStore.inspect_session_messages(query: SessionMessageQuery, *, expected_authorized_session_instance_id: str | None=None) -> SessionMessageInspection

apply_session_message_action (method)

async PostgresSessionStore.apply_session_message_action(request: SessionMessageActionRequest) -> SessionMessageActionResult

snapshot_session_message_source (method)

async PostgresSessionStore.snapshot_session_message_source(session_id: str, *, include_transcript_digest: bool=False, include_checkpoint_digest: bool=False, expected_authorized_session_instance_id: str | None=None) -> SessionMessageSource

deliver_queued_session_messages (method)

async PostgresSessionStore.deliver_queued_session_messages(session_id: str, *, include_on_idle: bool, reject_only: bool=False, delivery_id: str | None=None, eligible_through: int | None=None, limit: int=SESSION_MESSAGE_DELIVERY_BATCH_LIMIT, interaction_id: str | None=None, interaction_started_event: Event | None=None, profile_handoff: QueuedInteractionProfileHandoff | None=None) -> SessionMessageDeliveryBatch

repair_queued_interaction_profile_handoff (method)

async PostgresSessionStore.repair_queued_interaction_profile_handoff(session_id: str, *, interaction_started_event: Event, profile_handoff: QueuedInteractionProfileHandoff) -> ActiveInvocationExecutionProfile

publish_checkpoint_and_events (method)

async PostgresSessionStore.publish_checkpoint_and_events(session_id: str, *, checkpoint_transform: CheckpointTransform, events: list[Event], expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None) -> Session

publish_checkpoint_and_events_with_store_time (method)

async PostgresSessionStore.publish_checkpoint_and_events_with_store_time(session_id: str, *, idempotency_key: str, checkpoint_transform: StoreTimeCheckpointTransform, commit_time_guard: Callable[[datetime], None], events: list[Event], expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None) -> Session

Publish checkpoint state using the backend’s transactional clock.

load_session_operation (method)

async PostgresSessionStore.load_session_operation(session_id: str, idempotency_key: str, *, checkpoint_root_guard: CheckpointRootFieldGuard | None=None) -> dict[str, Any] | None

publish_session_operation (method)

async PostgresSessionStore.publish_session_operation(session_id: str, *, idempotency_key: str, operation_transform: SessionOperationTransform, events: list[Event], expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None) -> Session

supports_external_waits (method)

PostgresSessionStore.supports_external_waits() -> bool

publish_session_operation_guarded (method)

async PostgresSessionStore.publish_session_operation_guarded(session_id: str, *, idempotency_key: str, operation_transform: SessionOperationTransform, commit_guard: Callable[[], None], events: list[Event], expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None) -> Session

publish_session_operation_guarded_with_store_time (method)

async PostgresSessionStore.publish_session_operation_guarded_with_store_time(session_id: str, *, idempotency_key: str, operation_transform: StoreTimeSessionOperationTransform, commit_guard: Callable[[], None], commit_time_guard: Callable[[datetime], None], events: list[Event], expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None, context_view_compaction_cursor: int | None=None) -> Session

prepare_continuation_ticket (method)

async PostgresSessionStore.prepare_continuation_ticket(command: ContinuationPreparation) -> ContinuationRecord

Atomically retain one exact continuation ticket in ARMING state.

lookup_continuation_ticket (method)

async PostgresSessionStore.lookup_continuation_ticket(expected: ContinuationPreparation) -> ExactLookup[ContinuationRecord]

Return exact retained preparation evidence, never infer an outcome.

load_continuation_ticket (method)

async PostgresSessionStore.load_continuation_ticket(session_id: str, *, registration_key: str, session_instance_id: str) -> ContinuationRecord | None

Read one continuation aggregate without treating absence as proof.

mark_continuation_waiting (method)

async PostgresSessionStore.mark_continuation_waiting(ticket: ContinuationTicket) -> ContinuationRecord

Publish the ARMING-to-WAITING transition under the ticket’s CAS.

latch_continuation (method)

async PostgresSessionStore.latch_continuation(latch: ContinuationLatch) -> ContinuationRecord

Publish one immutable readiness latch, including an ARMING latch.

consume_continuation (method)

async PostgresSessionStore.consume_continuation(consumption: ContinuationConsumption) -> ContinuationRecord

Atomically elect one inline or queued continuation and replay it.

retire_continuation (method)

async PostgresSessionStore.retire_continuation(retirement: ContinuationRetirement) -> ContinuationRecord

Atomically retire a ticket, losing only to an already committed consume.

load_runtime_publication_receipt (method)

async PostgresSessionStore.load_runtime_publication_receipt(session_id: str, publication_id: str) -> RuntimePublicationReceipt | None

Load and verify one store-owned runtime publication receipt.

publish_runtime_publication (method)

async PostgresSessionStore.publish_runtime_publication(session_id: str, *, request: RuntimePublicationRequest, expected_statuses: set[SessionStatus] | None=None, expected_run_epoch: int | None=None, expected_transcript_cursor: int | None=None) -> RuntimePublicationResult

Atomically publish or exactly replay one logical runtime boundary.

load_model_completion_stage (method)

async PostgresSessionStore.load_model_completion_stage(session_id: str, stage_id: str) -> ModelCompletionStage | None

Load and verify append-only pre-dispatch and terminal completion evidence.

load_model_completion_stage_settlement (method)

async PostgresSessionStore.load_model_completion_stage_settlement(session_id: str, stage_id: str) -> ModelCompletionStageSettlement | None

Load verified terminal non-success evidence for one exact stage.

load_model_completion_stage_abandonment (method)

async PostgresSessionStore.load_model_completion_stage_abandonment(session_id: str, stage_id: str) -> ModelCompletionStageAbandonment | None

Read positive no-dispatch evidence after the preparation was removed.

This is a query, not permission to dispatch. Re-preparation compares the complete expected predecessor and this receipt in its own transaction. The shared operation-record lookup keeps all supported backends under their existing read owner; no second route cache is needed after restart.

load_active_model_completion_stage (method)

async PostgresSessionStore.load_active_model_completion_stage(session_id: str) -> ActiveModelCompletionStage | None

Load a verified snapshot of the dispatch currently eligible to publish.

load_model_completion_stage_dispatch (method)

async PostgresSessionStore.load_model_completion_stage_dispatch(session_id: str, stage_id: str) -> ModelCompletionStageDispatch | None

Load exact evidence that a prepared stage crossed the dispatch fence.

mark_model_completion_stage_dispatched (method)

async PostgresSessionStore.mark_model_completion_stage_dispatched(session_id: str, *, stage: ModelCompletionStage, consume_child_session_notifications: bool=True) -> ModelCompletionStageDispatch

Durably cross the last local fence before entering provider-controlled code.

prepare_model_completion_stage (method)

async PostgresSessionStore.prepare_model_completion_stage(session_id: str, *, request: ModelCompletionStageRequest, expected_statuses: set[SessionStatus], expected_run_epoch: int, expected_transcript_cursor: int) -> ModelCompletionStageResult

Insert or replay a stage; dispatch only when the result explicitly authorizes it.

complete_recovered_model_completion_stage (method)

async PostgresSessionStore.complete_recovered_model_completion_stage(session_id: str, *, stage_id: str, publication: RuntimePublicationRequest, recovery_fence: ModelCompletionStageRecoveryFence) -> ModelCompletionStageResult

Insert synthetic auxiliary terminal evidence under an atomic recovery fence.

Backends overriding the atomic hook must explicitly attest this protocol. Ordinary provider completion continues through complete_model_completion_stage.

complete_model_completion_stage (method)

async PostgresSessionStore.complete_model_completion_stage(session_id: str, *, stage_id: str, publication: RuntimePublicationRequest) -> ModelCompletionStageResult

Append or exactly replay immutable terminal provider-attempt material.

For auxiliary inference, terminal material records the explicit attempt outcome and accounting; it does not imply a successful model response.

abandon_model_completion_stage (method)

async PostgresSessionStore.abandon_model_completion_stage(session_id: str, *, stage_id: str, preparation_digest: str, expected_run_epoch: int, stage_source_run_epoch: int | None=None) -> ModelCompletionStageAbandonmentResult

Atomically abandon one exact active stage before provider dispatch.

An exact replay reconstructs the durable abandonment tombstone. A later preparation of the same request receives a new preparation digest, so a delayed retry of an older abandonment can never clear it.

promote_model_completion_stage (method)

async PostgresSessionStore.promote_model_completion_stage(session_id: str, *, stage_id: str, expected_run_epoch: int) -> RuntimePublicationResult

Atomically verify and publish a terminal stage without a load/publish race.

load_session_export_snapshot (method)

async PostgresSessionStore.load_session_export_snapshot(session_id: str, *, limits: SessionExportLimits | None=None) -> SessionExportSnapshot | None

load_events (method)

async PostgresSessionStore.load_events(session_id: str) -> list[Event]

load_user_input_supersession_events (method)

async PostgresSessionStore.load_user_input_supersession_events(session_id: str, input_id: str) -> list[Event]

load_tool_round_lifecycle_events (method)

async PostgresSessionStore.load_tool_round_lifecycle_events(session_id: str, tool_call_ids: list[str] | tuple[str, ...]) -> list[Event]

load_tool_round_lifecycle_events_for_round (method)

async PostgresSessionStore.load_tool_round_lifecycle_events_for_round(session_id: str, tool_call_ids: list[str] | tuple[str, ...], *, tool_round_identity: ToolRoundIdentity) -> list[Event]

query_events (method)

async PostgresSessionStore.query_events(query: EventQuery | None=None) -> list[EventRecord]

read_usage_accounting (method)

async PostgresSessionStore.read_usage_accounting(query: EventQuery, *, by_session: bool=False, by_identity: bool=False) -> UsageAccountingSnapshot

read_cost_accounting (method)

async PostgresSessionStore.read_cost_accounting(query: EventQuery, pricing: PriceBook, *, currency: str='USD', details: bool=False, by_session: bool=False, additional_events: tuple[Event, ...]=(), max_detail_bytes: int | None=None, previous: CostAccountingSnapshot | None=None) -> CostAccountingSnapshot

event_exists (method)

async PostgresSessionStore.event_exists(query: EventQuery) -> bool

query_events_bounded (method)

async PostgresSessionStore.query_events_bounded(query: EventQuery, *, max_bytes: int) -> list[EventRecord]

load_bounded (method)

async PostgresSessionStore.load_bounded(session_id: str, *, max_bytes: int) -> Session | None

export_terminal_session_evidence (method)

async PostgresSessionStore.export_terminal_session_evidence(session_id: str, *, spool: EvidenceSpool) -> None

Copy one stable terminal snapshot into caller-owned bounded backing.

load_terminal_session_evidence (method)

async PostgresSessionStore.load_terminal_session_evidence(session_id: str, *, limits: TerminalSessionEvidenceLimits | None=None) -> TerminalSessionEvidence

load_runner_owned_interrupted_evidence (method)

async PostgresSessionStore.load_runner_owned_interrupted_evidence(session_id: str, *, observed_events: tuple[RunnerObservedEventIdentity, ...] | None=None, expected_parent_session_id: str | None=None, limits: TerminalSessionEvidenceLimits | None=None) -> TerminalSessionEvidence

query_latest_interaction_events (method)

async PostgresSessionStore.query_latest_interaction_events(session_id: str, *, before_sequence: int | None=None, limit: int=100) -> list[EventRecord]

summarize_events (method)

async PostgresSessionStore.summarize_events(session_id: str) -> EventSummary

summarize_outcome (method)

async PostgresSessionStore.summarize_outcome(session_id: str) -> SessionOutcome

inspect_summary (method)

async PostgresSessionStore.inspect_summary(session_id: str, *, checkpoint_root_guard: CheckpointRootFieldGuard | None=None) -> SessionInspectionSummary

Return one exact, content-free diagnostic summary.

The default implementation deliberately composes the public paginated query contracts so out-of-tree stores gain the same semantics without a backend-specific schema dependency. Implementations may replace it with an equivalent bounded native aggregate.

list_sessions (method)

async PostgresSessionStore.list_sessions(query: SessionQuery | None=None) -> SessionListResult

query_session_topology (method)

async PostgresSessionStore.query_session_topology(query: SessionTopologyQuery) -> SessionTopologyStoreResult

query_session_lineage (method)

async PostgresSessionStore.query_session_lineage(query: SessionLineageQuery) -> SessionLineageResult

query_child_session_lifecycle (method)

async PostgresSessionStore.query_child_session_lifecycle(query: ChildSessionLifecycleQuery) -> ChildSessionLifecyclePage

aggregate_operational_snapshot (method)

async PostgresSessionStore.aggregate_operational_snapshot(filters: SessionAggregateFilter | None=None) -> SessionOperationalSnapshot

aggregate_usage (method)

async PostgresSessionStore.aggregate_usage(query: UsageRollupQuery) -> UsageRollupStoreResult

list_sessions_with_pending_interruption_cascade (method)

async PostgresSessionStore.list_sessions_with_pending_interruption_cascade(query: SessionQuery | None=None) -> SessionListResult

list_queued_dispatch_terminal_receipts (method)

async PostgresSessionStore.list_queued_dispatch_terminal_receipts(query: QueuedDispatchTerminalReceiptQuery | None=None) -> list[QueuedDispatchTerminalReceipt]

query_pending_actions (method)

async PostgresSessionStore.query_pending_actions(query: PendingActionQuery | None=None, *, checkpoint_root_guard: CheckpointRootFieldGuard | None=None) -> PendingActionListResult

validate_session_closure_admission (method)

async PostgresSessionStore.validate_session_closure_admission(session_id: str) -> None

load_session_closure_records (method)

async PostgresSessionStore.load_session_closure_records(session_id: str, *, max_records: int, max_bytes: int) -> dict[str, Any]

delete_session (method)

async PostgresSessionStore.delete_session(session_id: str, *, closure_receipt: dict[str, Any] | None=None, _access_bounds: _SessionAccessBounds | None=None) -> None

detach_session_children (method)

async PostgresSessionStore.detach_session_children(parent_session_id: str, child_session_ids: tuple[str, ...], *, closure_receipt: dict[str, Any]) -> tuple[dict[str, Any], ...]

load_session_closure_tombstones (method)

async PostgresSessionStore.load_session_closure_tombstones(root_session_id: str, plan_id: str) -> tuple[dict[str, Any], ...]

load_session_closure_receipt (method)

async PostgresSessionStore.load_session_closure_receipt(session_id: str, plan_id: str) -> dict[str, Any] | None

load_session_closure_progress (method)

async PostgresSessionStore.load_session_closure_progress(session_id: str, plan_id: str)

save_session_closure_progress (method)

async PostgresSessionStore.save_session_closure_progress(progress: dict[str, Any]) -> None

claim_session_closure_progress (method)

async PostgresSessionStore.claim_session_closure_progress(progress: dict[str, Any]) -> None

update_labels (method)

async PostgresSessionStore.update_labels(session_id: str, labels: dict[str, str], *, _access_bounds: _SessionAccessBounds | None=None) -> Session

update_metadata (method)

async PostgresSessionStore.update_metadata(session_id: str, metadata: dict[str, Any], *, _access_bounds: _SessionAccessBounds | None=None) -> Session

append_transcript_messages (method)

async PostgresSessionStore.append_transcript_messages(session_id: str, messages: list[Message], *, interaction_id: InteractionAttribution=INHERIT_INTERACTION) -> None

replace_initial_transcript_messages (method)

async PostgresSessionStore.replace_initial_transcript_messages(session_id: str, expected_messages: list[Message], replacement_messages: list[Message], *, interaction_id: InteractionAttribution=INHERIT_INTERACTION, checkpoint_transform: CheckpointTransform | None=None, runtime_suffix_count: int=0) -> None

load_deferred_interaction_input (method)

async PostgresSessionStore.load_deferred_interaction_input(session_id: str) -> DeferredInteractionInput | None

materialize_deferred_interaction_input (method)

async PostgresSessionStore.materialize_deferred_interaction_input(session_id: str, *, interaction_id: InteractionAttribution=INHERIT_INTERACTION) -> bool

append_transcript_messages_and_transform_checkpoint (method)

async PostgresSessionStore.append_transcript_messages_and_transform_checkpoint(session_id: str, messages: list[Message], checkpoint_transform: CheckpointTransform, *, interaction_id: InteractionAttribution=INHERIT_INTERACTION) -> None

load_transcript (method)

async PostgresSessionStore.load_transcript(session_id: str) -> list[Message]

load_transcript_snapshot (method)

async PostgresSessionStore.load_transcript_snapshot(session_id: str) -> TranscriptSnapshot

load_transcript_cursor (method)

async PostgresSessionStore.load_transcript_cursor(session_id: str) -> int

load_transcript_window (method)

async PostgresSessionStore.load_transcript_window(session_id: str, *, start_index: int, limit: int) -> TranscriptSnapshot

load_latest_transcript_message (method)

async PostgresSessionStore.load_latest_transcript_message(session_id: str, *, role: MessageRole) -> TranscriptRecord | None

load_latest_transcript_text (method)

async PostgresSessionStore.load_latest_transcript_text(session_id: str, *, role: MessageRole, max_chars: int) -> tuple[str, bool] | None

query_transcript (method)

async PostgresSessionStore.query_transcript(query: TranscriptQuery) -> TranscriptPage

search_transcript (method)

async PostgresSessionStore.search_transcript(query: TranscriptSearchQuery) -> TranscriptSearchResult

create_recall_receipt (method)

async PostgresSessionStore.create_recall_receipt(receipt: RecallReceipt) -> RecallReceipt

load_recall_receipt (method)

async PostgresSessionStore.load_recall_receipt(session_id: str, receipt_id: str) -> RecallReceipt | None

list_recall_receipts (method)

async PostgresSessionStore.list_recall_receipts(query: RecallEvidenceQuery) -> RecallReceiptPage

create_context_exposure (method)

async PostgresSessionStore.create_context_exposure(exposure: ContextExposure, item_exposures: tuple[RecallItemExposure, ...]=()) -> ContextExposure

load_context_exposure (method)

async PostgresSessionStore.load_context_exposure(session_id: str, exposure_id: str) -> ContextExposure | None

load_recall_item_exposures (method)

async PostgresSessionStore.load_recall_item_exposures(session_id: str, exposure_id: str) -> tuple[RecallItemExposure, ...]

list_context_exposures (method)

async PostgresSessionStore.list_context_exposures(query: RecallEvidenceQuery) -> ContextExposurePage

transition_context_exposure (method)

async PostgresSessionStore.transition_context_exposure(session_id: str, exposure_id: str, request: ContextExposureTransitionRequest) -> ContextExposure

checkpoint (method)

async PostgresSessionStore.checkpoint(session_id: str, state: dict[str, Any]) -> None

transform_checkpoint (method)

async PostgresSessionStore.transform_checkpoint(session_id: str, checkpoint_transform: CheckpointTransform) -> None

transform_checkpoint_with_store_time (method)

async PostgresSessionStore.transform_checkpoint_with_store_time(session_id: str, checkpoint_transform: StoreTimeCheckpointTransform) -> None

load_checkpoint (method)

async PostgresSessionStore.load_checkpoint(session_id: str) -> dict[str, Any] | None

load_interruption_cascade_marker (method)

async PostgresSessionStore.load_interruption_cascade_marker(session_id: str, *, checkpoint_root_guard: CheckpointRootFieldGuard | None=None) -> dict[str, Any] | None

Release source · Runtime guarantees · Capability guides