Persistence boundary for logical agent-session state.
A session is the aggregate root: turns, events, and requests are owned by a session and must not outlive it. Store implementations serialize writes made by a session before making them visible to readers.
Session snapshots are deliberately opaque. This keeps the persistence layer independent of the private session-process state while allowing a durable adapter to restore the public and provider identifiers it needs.
Events are append-only. events/3 uses an exclusive sequence cursor, so
after: 7 returns events whose sequence is greater than seven. A :turn_id
option asks the Store to filter by turn before applying its cursor and limit.
Public purge rejects a live SessionServer. Core-controlled startup
replacement and rollback may call delete_session/2 from a task whose owner
is that registered SessionServer; Stores that add their own live-delete guard
must allow that owner-bound case.
Summary
Types
@type event_options() :: [ after: non_neg_integer(), limit: non_neg_integer() | :infinity, turn_id: String.t() ]
@type owner() :: term()
@type request_options() :: [ turn_id: String.t(), status: AgentHarness.Request.status() ]
@type session_id() :: String.t()
@type session_snapshot() :: term()
Callbacks
@callback append_event(owner(), AgentHarness.Event.t()) :: :ok | {:error, term()}
@callback delete_session(owner(), session_id()) :: :ok | {:error, term()}
@callback events(owner(), session_id(), event_options()) :: {:ok, [AgentHarness.Event.t()]} | {:error, term()}
@callback fetch_request(owner(), session_id(), String.t()) :: {:ok, AgentHarness.Request.t()} | :not_found | {:error, term()}
@callback fetch_session(owner(), session_id()) :: {:ok, session_snapshot()} | :not_found | {:error, term()}
@callback fetch_turn(owner(), session_id(), String.t()) :: {:ok, AgentHarness.Turn.t()} | :not_found | {:error, term()}
@callback latest_sequence(owner(), session_id()) :: {:ok, non_neg_integer() | nil} | {:error, term()}
@callback list_requests(owner(), session_id(), request_options()) :: {:ok, [AgentHarness.Request.t()]} | {:error, term()}
@callback list_sessions(owner()) :: [{session_id(), session_snapshot()}]
@callback list_turns(owner(), session_id()) :: {:ok, [AgentHarness.Turn.t()]} | {:error, term()}
@callback save_request(owner(), AgentHarness.Request.t()) :: :ok | {:error, term()}
@callback save_session(owner(), session_id(), session_snapshot()) :: :ok | {:error, term()}
@callback save_turn(owner(), AgentHarness.Turn.t()) :: :ok | {:error, term()}