Struct SessionRepository 

pub struct SessionRepository { /* private fields */ }

Framework-owned coordinator over a session’s cache / storage / persistence tiers. Cheap to clone (all fields are Arc).

Implementations

impl SessionRepository

pub fn downgrade_parent_outcome_route(&self) -> ParentOutcomeRoute

pub async fn bind_parent_outcome_writer( &self, session_id: &str, ) -> Result<ParentOutcomeWriter>

A named adapter for trusted Host parent-request projections. Default saves retain their rejection boundary; request identity, lineage, deadline and single-winner validation remain in the original CAS.

impl SessionRepository

pub fn new( cache: SessionCache, storage: Arc<dyn Storage>, persistence: Arc<LockedSessionStore>, ) -> Self

pub fn with_root_actor_directory( self, directory: Arc<dyn ActorDirectoryPort>, ) -> Self

Enable durable ordinary Root execution ownership in a Host whose storage implements the named final writer boundary.

pub fn cache(&self) -> &SessionCache

pub fn storage(&self) -> &Arc<dyn Storage>

pub fn persistence(&self) -> &Arc<LockedSessionStore>

pub async fn load(&self, session_id: &str) -> Option<Session>

Load a session from the memory cache, falling back to durable storage (and back-filling the cache on a storage hit). None if absent in both.

pub async fn try_load(&self, session_id: &str) -> Result<Option<Session>>

Like load, but surfaces storage errors instead of swallowing them to None. Cache hit short-circuits; a storage hit back-fills the cache.

pub async fn save(&self, session: &mut Session) -> Result<()>

Persist the session (merge-on-write) and refresh the cache, surfacing storage errors. Use save_and_cache for the fire-and-forget variant that logs and continues on failure.

pub async fn save_replay_resolution(&self, session: &mut Session) -> Result<()>

Persist a blocked approval replay before starting its successor. A A save error may arrive after the rewritten result was committed. When the save was attempted, evict the old approval from cache under the same session lock so the next attempt reloads durable state.

pub async fn update_runtime_session<F>( &self, session_id: &str, metadata_keys: &[&str], mutate: F, ) -> Result<Option<Session>>

where F: FnOnce(&mut Session),

Atomically mutate the latest durable runtime session and refresh the cache with the saved value. This is the safe path for narrow metadata indexes that can be updated concurrently with runner message writes.

pub async fn load_or_create(&self, session_id: &str, model: &str) -> Session

Load a session, creating a fresh Session::new(id, model) if absent.

pub async fn load_merged_checked( &self, session_id: &str, ) -> Result<Option<Session>>

Load a session, reconciling the memory and storage copies via a preference heuristic: a live durable Root birth or mode epoch wins first; otherwise storage wins when it is strictly newer, or when it is the same age but still carries a pending question memory lost.

The cache is refreshed cache-aside. Timestamps cannot make a stale Root birth or mode epoch outrank verified durable authority.

pub async fn load_merged(&self, session_id: &str) -> Option<Session>

Compatibility wrapper for read paths where the historical contract treated a storage failure like absence. Mutating/recovery paths should use Self::load_merged_checked so they can preserve retry state.

pub async fn save_and_cache(&self, session: &mut Session)

Persist the session (merge-on-write, preserving concurrent UI edits to the authoritative metadata group) and refresh the in-memory cache.

Trait Implementations

impl Clone for SessionRepository

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl RuntimeSessionPersistence for SessionRepository

SessionRepository is the canonical RuntimeSessionPersistence: the runtime can persist a session through the same coordinator (merge-on-write + cache refresh) instead of a bespoke adapter.

fn inherited_child_wait(&self) -> Option<InheritedChildWait>

An execution-private binding, never reconstructed from mutable state.

fn bind_inherited_child_wait( &self, inherited: InheritedChildWait, ) -> Result<Arc<dyn RuntimeSessionPersistence>>

Return an execution-private view retaining the captured wait provenance through every intermediate save. Unsupported persisters fail closed.

fn root_actor_writer(&self) -> Option<RootActorRuntimeWrite>

Immutable capability already captured by this concrete execution. An unbound Host/default persister never supplies a current owner.

fn bind_root_inbox_receipt( &self, receipt: SessionInboxReceipt, ) -> Result<Arc<dyn RuntimeSessionPersistence>>

Execution-private input restriction. A selector carries no authority; only a persister already bound to a real Root writer may install it. Unsupported hosts fail closed. This introduces no durable state.

fn root_inbox_receipt(&self) -> Option<&SessionInboxReceipt>

fn root_actor_execution_required(&self, session: &Session) -> bool

Whether this Host requires an explicit execution capability for the proposed Root. A route without a bound event/persistence handoff must reject before claiming or making a provider call.

fn bind_root_actor_execution<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 Session, run_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<RootActorExecutionBinding>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Host execution binding, never a request DTO. Legacy embedders have no ActorDirectory; a host that enables one must reject unsupported storage before claiming rather than returning an unfenced writer.

fn save_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist the session, merging any newer authoritative metadata from disk.

fn supports_bound_startup_session(&self) -> bool

Whether this private writer supports the physical profile check.

fn save_bound_startup_session<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, expected: &'life2 Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Persist a Root-bound transition only if its original execution profile still matches under the backend’s physical writer and Root authority. Unsupported persisters must never emulate this with a separate read/save.

fn save_finalized_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist a runner’s final snapshot. Implementations with a per-session lock should reconcile a tool-registered child wait against the latest durable wait inside that lock: a child may finish after the runner’s last read but before this save. The default retains compatibility for in-memory and test persisters without that concurrent completion path.

fn save_finalized_runtime_with_inherited_child_wait<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, inherited: &'life2 WaitingForChildrenState, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Finalize a wait inherited by this execution. Backends must reconcile against durable state inside their cross-process write transaction. Unsupported adapters fail closed rather than reopen a read/save race.

fn seed_runtime_activation<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Authoritatively seed one validated actor activation.

fn record_permission_posture_activation<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, expected_audit_revision: Option<u64>, seed: &'life2 PermissionAuditSeed, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically persist a worker-declared executor mapping for the current host-authoritative permission posture.

fn save_runtime_control_plane<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist only the runtime control-plane for a session.

fn load_runtime_control_plane<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load the representation paired with save_runtime_control_plane.

fn update_task_list_control_plane<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session_id: &'life1 str, task_list: &'life2 TaskList, version: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Atomically update only the shared Task list and its version.

fn update_task_list_control_plane_if_version<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, session_id: &'life1 str, expected_version: &'life2 str, expected_task_list: &'life3 TaskList, task_list: &'life4 TaskList, version: &'life5 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait,

Atomically update Task-owned control-plane fields only when the durable Task generation and exact list still match the expected snapshot.

fn update_task_list_control_planes_if_version<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>( &'life0 self, session_id: &'life1 str, shared_session_id: &'life2 str, expected_version: &'life3 str, expected_task_list: &'life4 TaskList, task_list: &'life5 TaskList, version: &'life6 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait,

Recoverably compare-and-patch the executing session and its shared root. Implementations must validate both generations before either target is written and may return Ok(true) only after both Task generations are durable with no undo record that could later revert them. An error after one physical write must restore both originals before returning or retain durable recovery state and fail subsequent paired access closed until recovery completes. Root-session callers pass the same id twice and receive the single-target CAS semantics above.

fn checkpoint_live_bootstrap<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 Session, inbox: Arc<dyn SessionInboxPort>, gate: AdmissionGate, ) -> Pin<Box<dyn Future<Output = Result<LiveBootstrapProof>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Bound execution only; unsupported/custom adapters cannot authorize a continuation by falling back to generic checkpoint or snapshot reads.

fn confirm_live_bootstrap<'life0, 'life1, 'async_trait>( &'life0 self, proof: &'life1 LiveBootstrapProof, inbox: Arc<dyn SessionInboxPort>, publish: RootActorRuntimeEventPublisher, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn checkpoint_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Append-safe checkpoint used at the shared engine execute boundary.

fn claim_scoped_loop_controls<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 Session, inbox: Arc<dyn SessionInboxPort>, active_run_id: &'life2 str, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<ScopedLoopControlClaim>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Only the existing owner may claim structured Loop inputs. Unsupported adapters do not fall back to ordinary provider-message admission.

fn checkpoint_scoped_loop_control<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, bindings: &'life2 [ScopedLoopControlBinding], activation: Arc<dyn SessionActivationPort>, input: Option<(Arc<dyn SessionInboxPort>, ScopedLoopControlClaim)>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

State, immutable control outcome and typed consumption proof share the actual target checkpoint; ACK is last. Err never means rollback.

fn load_loop_control_checkpoint<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Canonical read after a failed/uncertain checkpoint. A cached Session or the proposed caller snapshot is not confirmation of what was written.

fn admit_root_inbox<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, inbox: Arc<dyn SessionInboxPort>, active_run_id: Option<&'life2 str>, ) -> Pin<Box<dyn Future<Output = Result<Option<RootInboxAdmission>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn checkpoint_retrieval_window<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, expected_base: &'life1 Session, staged: &'life2 mut Session, ) -> Pin<Box<dyn Future<Output = Result<RetrievalWindowCheckpointOutcome>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically commit a staged archive transcript rewrite.

fn checkpoint_prompt_rewrite<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, expected_base: &'life1 Session, staged: &'life2 mut Session, ) -> Pin<Box<dyn Future<Output = Result<RetrievalWindowCheckpointOutcome>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically commit a provider-visible System-prompt rewrite.

fn checkpoint_manual_archive_rejection<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, expected_base: &'life1 Session, staged: &'life2 mut Session, ) -> Pin<Box<dyn Future<Output = Result<RetrievalWindowCheckpointOutcome>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically commit one permanently rejected archive_context result.

fn checkpoint_manual_archive_consumption<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, expected_base: &'life1 Session, staged: &'life2 mut Session, ) -> Pin<Box<dyn Future<Output = Result<RetrievalWindowCheckpointOutcome>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically consume one successful no-op archive_context request.

fn load_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load the latest runtime-visible session snapshot when the persistence implementation can coordinate reads. Tools may update a repository-owned clone while an agent loop holds its own live Session; the loop uses this hook to merge narrowly-scoped tool side effects before its next save.

fn load_runtime_admission_snapshot<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read a canonical snapshot for execution admission without publishing or trusting a cached clone. Preserve the same bound-reader checks as the runtime loader. A persister with a cache must override this operation to read its durable source (or return Unsupported); the default serves uncached/legacy loaders. This read never grants execution/write authority.

fn clear_legacy_pending_messages<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, expected: &'life2 [Value], ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Clear the bounded compatibility queue iff it still equals the entries that were durably copied into SessionInbox. Implementations with a per-session transaction should override this method.

fn append_token_usage_record<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, json_line: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Append one JSON-line analysis record to the session’s append-only token-usage log (see Storage::append_token_usage_record). Defaults to a no-op so non-file-backed persisters are unaffected.

impl SessionAccess for SessionRepository

The framework-owned SessionRepository is the canonical SessionAccess. Server AppState delegates to its session_repo; SDK / in-process callers can use a SessionRepository directly as a SessionAccess.

fn bind_response_writer( &self, owner: Option<RootActorRuntimeWrite>, ) -> Result<Option<Arc<dyn SessionAccess>>, SessionSaveError>

Use the exact successor’s Root capability for a response CAS. External adapters without the named writer reject a Root handoff before consume.

fn bind_response_writer_with_inherited( &self, owner: Option<RootActorRuntimeWrite>, inherited: Option<InheritedChildWait>, ) -> Result<Option<Arc<dyn SessionAccess>>, SessionSaveError>

Bind a response writer while retaining the successor’s captured wait. Implementations that cannot retain this provenance must fail closed.

fn load_session<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session by ID (from cache or storage).

fn load_or_create<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 str, model: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Session, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Load an existing session or create a new one with the given model.

fn load_merged<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session, merging memory and storage using a preference heuristic.

fn save_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage only.

fn save_and_cache<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage and update the in-memory cache.

fn inspect_for_response<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Inspect the authoritative snapshot used by a pending-response transaction, without mutating it. Canonical repositories override this so durable consumed-response state wins over a stale cache candidate.

fn mutate_for_response<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, mutate: Box<dyn for<'session> FnOnce(&'session mut Session) -> Result<(), RespondError> + Send + 'static>, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, RespondError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Compare/mutate/persist the latest session for a pending response. Implementations backed by a canonical per-session lock override this so the whole operation is atomic. The default preserves compatibility for lightweight/in-memory adapters; the respond use case also serializes its entrypoints so those adapters cannot double-consume concurrently.