Struct ActiveSession 

pub struct ActiveSession {
    pub metadata: Arc<SessionMetadata>,
    pub last_updated: DateTime<Utc>,
    pub hot_context: Arc<HotContext>,
    pub warm_context: Arc<Vec<CompressedUpdate>>,
    pub cold_context: Arc<Vec<StructuredSummary>>,
    pub current_state: Arc<StructuredContext>,
    pub incremental_updates: Arc<Vec<ContextUpdate>>,
    pub code_references: Arc<HashMap<String, Vec<CodeReference>>>,
    pub change_history: Arc<Vec<ChangeRecord>>,
    pub entity_graph: Arc<SimpleEntityGraph>,
    pub vectorized_update_ids: Arc<DashSet<Uuid>>,
}

ActiveSession with lock-free granular components Uses Arc-wrapped lock-free structures for concurrent access and cheap cloning

Copy-on-Write (CoW) Semantics: Heavy fields are wrapped in Arc for efficient cloning. When the session needs to be modified, use Arc::make_mut() which will:

• Return a mutable reference if this is the only owner
• Clone the data only if there are other owners

This dramatically reduces cloning overhead when sessions are frequently updated.

Fields

metadata: Arc<SessionMetadata>

Immutable session metadata (id, name, preferences)

last_updated: DateTime<Utc>

Timestamp of the last modification

hot_context: Arc<HotContext>

Lock-free hot updates (DashMap-based)

warm_context: Arc<Vec<CompressedUpdate>>

CoW compressed updates (storage tier)

cold_context: Arc<Vec<StructuredSummary>>

CoW periodic summaries (storage tier)

current_state: Arc<StructuredContext>

Current queryable structured state

incremental_updates: Arc<Vec<ContextUpdate>>

All incremental updates (biggest CoW vector)

code_references: Arc<HashMap<String, Vec<CodeReference>>>

Code references indexed by file path

change_history: Arc<Vec<ChangeRecord>>

Recorded change history

entity_graph: Arc<SimpleEntityGraph>

Named-entity graph with relationships

vectorized_update_ids: Arc<DashSet<Uuid>>

IDs of updates that have been vectorized

Implementations

impl ActiveSession

pub fn new( id: Uuid, name: Option<String>, description: Option<String>, ) -> ActiveSession

Create a new empty session with default preferences.

pub fn from_components( id: Uuid, name: Option<String>, description: Option<String>, created_at: DateTime<Utc>, last_updated: DateTime<Utc>, user_preferences: UserPreferences, hot_context_vec: Vec<ContextUpdate>, warm_context: Vec<CompressedUpdate>, cold_context: Vec<StructuredSummary>, current_state: StructuredContext, incremental_updates: Vec<ContextUpdate>, code_references: HashMap<String, Vec<CodeReference>>, change_history: Vec<ChangeRecord>, entity_graph: SimpleEntityGraph, vectorized_update_ids: Vec<Uuid>, ) -> ActiveSession

Reconstruct an ActiveSession from individual components (used for SurrealDB native storage)

pub fn id(&self) -> Uuid

Returns the session’s unique identifier.

pub fn is_vectorization_pending(&self, entry_id: Uuid) -> bool

Returns true if entry_id is queued for vectorisation but the embedding has not yet landed in the vector index.

pub fn pending_vectorization_count(&self) -> usize

Returns the number of context entries currently waiting for the embedding pipeline. Useful as a per-session counterpart to Pipeline::backlog() (which is process-wide).

pub fn name(&self) -> Option<String>

Returns the session’s display name, if set.

pub fn description(&self) -> Option<String>

Returns the session’s description, if set.

pub fn created_at(&self) -> DateTime<Utc>

Returns the session creation timestamp.

pub fn user_preferences(&self) -> &UserPreferences

Returns a reference to the session’s user preferences.

pub async fn add_incremental_update( &mut self, update: ContextUpdate, ) -> Result<(), Error>

Add an incremental update, processing entity graph, code refs, and state.

pub async fn add_incremental_update_fast( &mut self, update: ContextUpdate, ) -> Result<(), Error>

Fast path: same as add_incremental_update but skips update_entity_graph. Entity graph update should be applied separately via apply_entity_graph_update.

pub async fn apply_entity_graph_update( &mut self, update: &ContextUpdate, ) -> Result<(), Error>

Apply entity graph update only. Used as background task after CAS success.

pub fn remove_update_by_id(&mut self, entry_id: &Uuid) -> bool

Remove a single incremental update by its ContextUpdate.id (entry_id).

Cleans up the hot context cache, the warm-compressed cache, and the canonical incremental_updates vector. Returns true if the entry existed. Caller is responsible for persisting the session and (optionally) rebuilding the entity graph if relations from this update should be revoked.

pub fn remove_updates_for_file(&mut self, file_path: &str) -> usize

Remove incremental updates whose related_code.file_path matches file_path. Also removes the corresponding code_references entry. Returns the number of updates removed.

pub async fn rebuild_entity_graph_from_updates( &mut self, ) -> Result<(usize, usize), Error>

Rebuild the entity graph by clearing it and replaying all updates through NER extraction. Returns (entities_before, entities_after) counts.

pub fn set_name(&mut self, name: Option<String>)

Update the session name (preserves created_at).

pub fn set_description(&mut self, description: Option<String>)

Update the session description (preserves created_at).

pub fn update_metadata( &mut self, name: Option<String>, description: Option<String>, )

Update both name and description (preserves existing values if None provided, and always preserves the original created_at).

pub fn get_metadata(&self) -> (Option<String>, Option<String>)

Get the current name and description

pub async fn add_context_update( &mut self, description: String, metadata: Option<Value>, ) -> Result<(String, ContextUpdate), String>

Build a ContextUpdate from a description (or deserialize one from caller metadata) and append it via add_incremental_update_fast. Returns (update_id, update).

pub fn context_summary(&self) -> String

Recent updates from hot context as a human-readable bullet list.

Trait Implementations

impl Clone for ActiveSession

fn clone(&self) -> ActiveSession

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ActiveSession

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ActiveSession

fn default() -> ActiveSession

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ActiveSession

fn deserialize<D>( deserializer: D, ) -> Result<ActiveSession, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ActiveSession

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.