cayu.storage.sqlite

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.

SQLiteSessionStore

from cayu.storage import SQLiteSessionStore

SQLite-backed session store for durable local runtime state.

Decorators: @model_store_surface('sessions').

Bases: SQLiteExternalWaitMixin, SQLiteSessionExecutionMixin, SQLiteContextSelectionFenceMixin, SQLiteCreationFenceMixin, 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.UNVERIFIED

inspect_session_execution (method)

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

Read observational liveness; custom stores without leases return unknown.

read_context_view_selection_decision (method)

async SQLiteSessionStore.read_context_view_selection_decision(request)

Exact receiving readback, not current disclosure or ownership authority.

list_pending_session_creations (method)

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

read_session_creation_decision (method)

async SQLiteSessionStore.read_session_creation_decision(target)

create_participant_owned_session (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_participant_session_binding(session_id)

load_participant_session_creation_receipt (method)

async SQLiteSessionStore.load_participant_session_creation_receipt(session_id)

lookup_participant_session_creation (method)

async SQLiteSessionStore.lookup_participant_session_creation(creation_request)

capture_context_view_publication_source (method)

async SQLiteSessionStore.capture_context_view_publication_source(session_id)

capture_recipient_continuation (method)

async SQLiteSessionStore.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 SQLiteSessionStore.publish_context_view(manifest, *, publication_key)

lookup_context_view_selection (method)

async SQLiteSessionStore.lookup_context_view_selection(selection_key)

lookup_context_view_publication (method)

async SQLiteSessionStore.lookup_context_view_publication(publication_key)

select_context_view (method)

async SQLiteSessionStore.select_context_view(request)

read_context_view (method)

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

transition_context_view_ownership (method)

async SQLiteSessionStore.transition_context_view_ownership(request)

validate_context_view_source_closure (method)

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

validate_context_view_compaction (method)

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

read_context_view_lifecycle_events (method)

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

durable_state_paths (method)

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

Return the primary SQLite file for state-boundary validation.

public_authority_alias_codec (property)

SQLiteSessionStore.public_authority_alias_codec() -> PublicAuthorityAliasCodec | None

Return the immutable codec bound to this store’s durable alias registry.

register_public_authority_alias (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.public_authority_private_value_exists(private_value: str, *, field_name: str, scope_session_id: str | None=None) -> bool

issue_targeted_tool_grants (method)

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

list_targeted_tool_grants (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_targeted_tool_grant_state(session_id: str) -> TargetedToolGrantStateSnapshot

bind_targeted_tool_grant_use (method)

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

revoke_targeted_tool_grant (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.load(session_id: str) -> Session | None

load_state (method)

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

load_invocation_snapshot (method)

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

inspect_identity (method)

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

update_status (method)

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

transition_status (method)

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

transition_status_and_checkpoint (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.admit_session_invocation(session_id: str, *, admission: SessionInvocationAdmission) -> Session

Atomically claim one valid profiled invocation and its interaction.

apply_invocation_lifecycle_command (method)

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

Apply one command only after authenticating the store protocol.

settle_session_invocation (method)

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

release_session_invocation (method)

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

reject_execution_profile_resume (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.load_interaction_transition_receipt(session_id: str, *, transition: InteractionTransitionSpec, expected_recovery_claim_id: str | None=None) -> InteractionTransitionReceiptResult | None

load_historical_interaction_settlement (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.fence_stalled_run(session_id: str, *, statuses: set[SessionStatus], inactive_for_seconds: int) -> Session | None

reserve_stalled_run_recovery (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.release_run_fence(session_id: str) -> None

claim_budget_reservation_identity (method)

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

append_event (method)

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

append_events (method)

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

append_workflow_step_started (method)

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

append_tool_effect_conflict (method)

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

load_mcp_manifest_baselines (method)

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

compare_and_publish_mcp_manifest_checks (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.get_persisted_event_side_effect_delivery(*, session_id: str, event_id: str) -> PersistedEventSideEffectDelivery | None

claim_first_persisted_event_side_effect (method)

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

retire_failed_first_event_delivery (method)

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

mark_persisted_event_side_effect_delivered (method)

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

mark_persisted_event_side_effect_failed (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.get_persisted_event_side_effect_health() -> PersistedEventSideEffectHealth

query_persisted_event_side_effect_deliveries (method)

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

defer_persisted_event_side_effect (method)

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

renew_persisted_event_side_effect (method)

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

enqueue_session_message (method)

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

append_peer_content (method)

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

read_peer_content (method)

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

exclude_peer_content (method)

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

read_peer_content_attempt (method)

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

list_pending_peer_content (method)

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

Trusted receiving-owner discovery, independent of creation settlement.

retry_pending_peer_content (method)

async SQLiteSessionStore.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 SQLiteSessionStore.record_peer_content_exposure(request: PeerContentExposureRequest) -> PeerContentExposureReceipt

begin_peer_content_exposure (method)

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

read_peer_content_exposure (method)

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

inspect_session_messages (method)

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

apply_session_message_action (method)

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

snapshot_session_message_source (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.repair_queued_interaction_profile_handoff(session_id: str, *, interaction_started_event: Event, profile_handoff: QueuedInteractionProfileHandoff) -> ActiveInvocationExecutionProfile

publish_checkpoint_and_events (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.load_session_operation(session_id: str, idempotency_key: str, *, checkpoint_root_guard: CheckpointRootFieldGuard | None=None) -> dict[str, Any] | None

publish_session_operation (method)

async SQLiteSessionStore.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)

SQLiteSessionStore.supports_external_waits() -> bool

publish_session_operation_guarded (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.prepare_continuation_ticket(command: ContinuationPreparation) -> ContinuationRecord

Atomically retain one exact continuation ticket in ARMING state.

lookup_continuation_ticket (method)

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

Return exact retained preparation evidence, never infer an outcome.

load_continuation_ticket (method)

async SQLiteSessionStore.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 SQLiteSessionStore.mark_continuation_waiting(ticket: ContinuationTicket) -> ContinuationRecord

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

latch_continuation (method)

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

Publish one immutable readiness latch, including an ARMING latch.

consume_continuation (method)

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

Atomically elect one inline or queued continuation and replay it.

retire_continuation (method)

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

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

load_runtime_publication_receipt (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.load_session_export_snapshot(session_id: str, *, limits: SessionExportLimits | None=None) -> SessionExportSnapshot | None

load_events (method)

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

load_user_input_supersession_events (method)

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

load_tool_round_lifecycle_events (method)

async SQLiteSessionStore.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 SQLiteSessionStore.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 SQLiteSessionStore.query_events(query: EventQuery | None=None) -> list[EventRecord]

read_usage_accounting (method)

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

read_cost_accounting (method)

async SQLiteSessionStore.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 SQLiteSessionStore.event_exists(query: EventQuery) -> bool

query_events_bounded (method)

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

load_bounded (method)

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

export_terminal_session_evidence (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_terminal_session_evidence(session_id: str, *, limits: TerminalSessionEvidenceLimits | None=None) -> TerminalSessionEvidence

load_runner_owned_interrupted_evidence (method)

async SQLiteSessionStore.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 SQLiteSessionStore.query_latest_interaction_events(session_id: str, *, before_sequence: int | None=None, limit: int=100) -> list[EventRecord]

summarize_events (method)

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

summarize_outcome (method)

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

inspect_summary (method)

async SQLiteSessionStore.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 SQLiteSessionStore.list_sessions(query: SessionQuery | None=None) -> SessionListResult

query_session_topology (method)

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

query_session_lineage (method)

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

query_child_session_lifecycle (method)

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

aggregate_operational_snapshot (method)

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

aggregate_usage (method)

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

list_sessions_with_pending_interruption_cascade (method)

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

list_queued_dispatch_terminal_receipts (method)

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

query_pending_actions (method)

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

validate_session_closure_admission (method)

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

load_session_closure_records (method)

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

delete_session (method)

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

detach_session_children (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_session_closure_tombstones(root_session_id: str, plan_id: str) -> tuple[dict[str, Any], ...]

load_session_closure_receipt (method)

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

load_session_closure_progress (method)

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

save_session_closure_progress (method)

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

claim_session_closure_progress (method)

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

update_labels (method)

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

update_metadata (method)

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

append_transcript_messages (method)

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

replace_initial_transcript_messages (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_deferred_interaction_input(session_id: str) -> DeferredInteractionInput | None

materialize_deferred_interaction_input (method)

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

append_transcript_messages_and_transform_checkpoint (method)

async SQLiteSessionStore.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 SQLiteSessionStore.load_transcript(session_id: str) -> list[Message]

load_transcript_snapshot (method)

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

load_transcript_cursor (method)

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

load_transcript_window (method)

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

load_latest_transcript_message (method)

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

load_latest_transcript_text (method)

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

query_transcript (method)

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

search_transcript (method)

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

create_recall_receipt (method)

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

load_recall_receipt (method)

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

list_recall_receipts (method)

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

create_context_exposure (method)

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

load_context_exposure (method)

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

load_recall_item_exposures (method)

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

list_context_exposures (method)

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

transition_context_exposure (method)

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

checkpoint (method)

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

transform_checkpoint (method)

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

transform_checkpoint_with_store_time (method)

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

load_checkpoint (method)

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

load_interruption_cascade_marker (method)

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

init (method)

SQLiteSessionStore.__init__(path: str | Path, *, schema_mode: schema.SchemaMode=schema.SchemaMode.CREATE, read_only: bool=False, public_authority_alias_codec: PublicAuthorityAliasCodec | None=None, ownership_clock: Callable[[], datetime] | None=None) -> None

prune_events (method)

async SQLiteSessionStore.prune_events(*, before: datetime, session_id: str | None=None) -> int

Delete events older than before to bound unbounded event growth.

before is compared against each event’s timestamp (events strictly older are removed). When session_id is given the prune is scoped to that session (which must exist); otherwise every session is pruned. The latest active or paused interaction lifecycle event is retained until a terminal event replaces it. Sessions with an active model-completion stage, pending tool round, or immutable runtime-publication receipt, or unacknowledged queued-dispatch terminal receipt are retained because deleting their evidence would make exact recovery or receipt replay impossible. Immutable profiled-fork decision and fork events are likewise retained while their child relationship exists. Targeted-grant issuance, accepted-consumption, revocation, and fork-reset evidence is retained because the durable grant state uses it to validate exact retry and negative inheritance authority. Queue lifecycle events and their sequence/side-effect records are retained while the event-owned session and queue identity still name a queue row, including terminal rows. Queue JSON is not parsed to establish this pin. Returns the number of events deleted.

compact_transcript (method)

async SQLiteSessionStore.compact_transcript(session_id: str, *, keep_last: int) -> int

Compact a session’s transcript, keeping only its most recent messages.

Retains the keep_last newest transcript messages (by insertion order) for session_id and deletes the rest, bounding transcript growth for long-lived sessions. Active model stages, pending tool rounds, and immutable publication receipts pin their recovery material. Active model-target projection runs also pin the transcript; their permanent absolute cursor makes retention safe again at a terminal boundary. Returns the number of messages deleted.

close (method)

async SQLiteSessionStore.close() -> None

Release source · Runtime guarantees · Capability guides