yera.ui.sessions_store.base

Define persisted session records and their storage contract.

A session record holds navigation and lifecycle metadata. Its ordered event log contains the output and persistence-safe input needed to reconstruct a transcript without executing the app again.

Symbols

class BaseSessionStore — Define storage for session metadata and ordered event histories.
class SessionRecord — Describe one persisted Yera app session.
class SessionRecordUpdate — Describe metadata to persist atomically with an event.
class StoredEventRecord — Pair a persisted runtime event with its authoritative storage time.

BaseSessionStore

Inherits: ABC
Subclasses: SQLiteSessionStore

Define storage for session metadata and ordered event histories.

Implementations must preserve event order and support atomically appending an event with an optional title or lifecycle update. Stores are context managers: callers open them before use and close their underlying resources when the server exits.

Methods

create — Creates a new session in the store.
has — Checks if a session exists in the store.
has_events — Report whether a session has any persisted runtime history.
get — Retrieves a session record by its ID.
list — Lists all stored session records.
update — Updates the metadata of an existing session.
append_event — Append one event and optionally update session metadata atomically.
read_records — Read timestamped event records in append order.
read_events — Read a session's typed event history in append order.
__enter__ — Open the store for session operations.
__exit__ — Close resources owned by the store.

BaseSessionStore.create

create(
    app_id: str,
) → SessionRecord

Creates a new session in the store.

Parameters

app_id
type: str

The ID of the application associated with the session.

Returns

type: SessionRecord

The created SessionRecord.

BaseSessionStore.has

has(
    session_id: str,
) → bool

Checks if a session exists in the store.

Parameters

session_id
type: str

The unique identifier of the session.

Returns

type: bool

True if the session exists, False otherwise.

BaseSessionStore.has_events

has_events(
    session_id: str,
) → bool

Report whether a session has any persisted runtime history.

The server uses this distinction to launch a genuinely new session but replay an existing transcript without executing its app again.

Parameters

session_id
type: str

Session whose event history is inspected.

Returns

type: bool

True when at least one event is stored.

BaseSessionStore.get

get(
    session_id: str,
) → SessionRecord

Retrieves a session record by its ID.

Parameters

session_id
type: str

The unique identifier of the session.

Returns

type: SessionRecord

The requested SessionRecord.

BaseSessionStore.list

list() → list[SessionRecord]

Lists all stored session records.

Returns

type: list[SessionRecord]

A list of all SessionRecords.

BaseSessionStore.update

update(
    session_id: str,
    title: str | None = None,
    status: SessionStatus | None = None,
) → None

Updates the metadata of an existing session.

Parameters

session_id
type: str

The unique identifier of the session.

title
type: str | None = None

An optional new title for the session.

status
type: SessionStatus | None = None

An optional new lifecycle status for the session.

BaseSessionStore.append_event

append_event(
    session_id: str,
    event: OutputEvent | InputEvent,
    update: SessionRecordUpdate | None = None,
) → None

Append one event and optionally update session metadata atomically.

Implementations must preserve append order and update updated_at in the same transaction as the event. This prevents transcript history and lifecycle state from diverging when recording an input request, exit, or title change.

Parameters

session_id
type: str

Session receiving the event.

event
type: OutputEvent | InputEvent

Typed runtime input or output event to persist.

update
type: SessionRecordUpdate | None = None

Optional title or lifecycle change committed with the event.

BaseSessionStore.read_records

read_records(
    session_id: str,
) → Iterator[StoredEventRecord]

Read timestamped event records in append order.

The record timestamp describes when the store committed the event. It is distinct from any producer timestamp carried by the event itself.

Parameters

session_id
type: str

Session whose timestamped history is read.

Returns

type: Iterator[StoredEventRecord]

An iterator of stored records in append order.

BaseSessionStore.read_events

read_events(
    session_id: str,
) → Iterator[OutputEvent | InputEvent]

Read a session's typed event history in append order.

This compatibility API projects events from :meth:read_records, so timestamp-aware and event-only consumers share the same deserialization behavior.

Parameters

session_id
type: str

Session whose history is read.

Returns

type: Iterator[OutputEvent | InputEvent]

An iterator of deserialized input and output events in append order.

BaseSessionStore.__enter__

__enter__() → Self

Open the store for session operations.

Returns

type: Self

The open session store.

BaseSessionStore.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) → None

Close resources owned by the store.

Parameters

exc_type
type: type[BaseException] | None

Type of exception leaving the context, if any.

exc_val
type: BaseException | None

Exception instance leaving the context, if any.

exc_tb
type: TracebackType | None

Traceback associated with the exception, if any.

SessionRecord

Inherits: BaseModel

Describe one persisted Yera app session.

Fields

id
type: str (required)

Stable session identifier.

app_id
type: str (required)

App originally associated with the session.

title
type: str (required)

User-facing session title.

created_at
type: datetime.datetime (required)

UTC time at which the session was created.

updated_at
type: datetime.datetime (required)

UTC time of the latest metadata or event change.

status
type: Literal['created', 'running', 'waiting', 'completed', 'failed', 'interrupted'] = 'created'

Current persisted lifecycle state.

Methods

new — Create initial metadata for a new app session.

SessionRecord.new

new(
    app_id: str,
    title: str | None = None,
) → SessionRecord

Create initial metadata for a new app session.

The record receives a UUID, matching creation and update timestamps, and the created lifecycle state. When no title is supplied, a short portion of the UUID provides a unique placeholder title.

Parameters

app_id
type: str

Stable identifier of the session's app.

title
type: str | None = None

Optional initial user-facing title.

Returns

type: SessionRecord

A new, unpersisted session record.

SessionRecordUpdate

Inherits: BaseModel

Describe metadata to persist atomically with an event.

Fields

title
type: str | None = None

Replacement session title, or None to retain the current one.

status
type: Optional[Literal['created', 'running', 'waiting', 'completed', 'failed', 'interrupted']] = None

Replacement lifecycle state, or None to retain the current one.

StoredEventRecord

Inherits: BaseModel

Pair a persisted runtime event with its authoritative storage time.

Fields

event
type: yera.runtime.models.out_event.OutputEvent | yera.runtime.models.in_event.InputEvent (required)

Typed runtime event reconstructed from storage.

created_at
type: datetime.datetime (required)

UTC time at which the event was committed to the store.