Struct Session 

pub struct Session {
    pub id: String,
    pub session_scope: String,
    pub workflow: Workflow,
    pub identity: AgentIdentity,
    pub loop_state: SessionLoopState,
    pub chain: Mutex<EventChain>,
    pub atif: Mutex<TrajectoryBuilder>,
    pub totals: Totals,
    pub last_activity_ms: AtomicU64,
    pub closed: AtomicU64,
    pub receipt: Mutex<Option<Receipt>>,
    pub atif_path: Mutex<Option<PathBuf>>,
    /* private fields */
}

A live session.

Fields

id: String

Session id.

session_scope: String

A per-open UUID that disambiguates recycled session ids in the off-path vector store. Client callers may reuse the same id after a finalize; the SessionRegistry::get_or_open path historically returned a fresh Session under the same key. A Qdrant vector search filtered ONLY on session_id would then return the prior incarnation’s vectors, causing false semantic-loop signals from an unrelated past session. Every vector record and query is now scoped by session_scope = "{id}#{generation_uid}" — the UUID is fresh for every Session::new, so a recycled id lands in a distinct scope. The bare id remains the primary key for on-disk artifacts (spool paths, journal filenames), which use crash-safe generation logic of their own.

workflow: Workflow

Workflow kind.

identity: AgentIdentity

Agent identity bound at open (from NHI validation).

loop_state: SessionLoopState

Loop-breaker state.

chain: Mutex<EventChain>

Signed workflow: incremental event chain.

atif: Mutex<TrajectoryBuilder>

Unsigned workflow: ATIF steps.

totals: Totals

Aggregates for the receipt.

last_activity_ms: AtomicU64

Last-activity timestamp (dashboard/display only), epoch ms. Wall-clock time subject to VM/NTP jumps; not safe to use for idle-eviction decisions — the private last_activity_instant field carries a monotonic anchor the idle sweeper uses instead.

closed: AtomicU64

Set once closed (idempotent close).

receipt: Mutex<Option<Receipt>>

Issued signed or retroactive receipt.

atif_path: Mutex<Option<PathBuf>>

Persisted unsigned ATIF artifact.

Implementations

impl Session

pub fn new( id: String, workflow: Workflow, identity: AgentIdentity, breaker: BreakerConfig, ) -> Self

Open a session.

pub fn next_seq(&self) -> u64

Next event sequence number.

pub fn touch(&self)

Touch the activity clock. Both the wall-clock and the monotonic anchors are updated: the wall-clock feeds dashboard display, the monotonic feeds the idle sweeper.

pub fn try_close(&self) -> bool

Attempt to claim the close transition. Only one caller can hold the claim at a time; a failed finalize resets it (reset_close) so the close can be retried.

pub fn lifecycle_state(&self) -> SessionState

The lifecycle chain position.

pub fn is_closed(&self) -> bool

True when closed: the close claim is held (closed — a claim flag, not a chain position; see transition) or the lifecycle chain is at/past Sealed.

pub fn artifact_committed_flag(&self) -> bool

True once the receipt/ATIF artifact is durably persisted.

pub fn close_complete_flag(&self) -> bool

True once the close ran to full completion (journal removed).

pub fn try_promote(&self) -> bool

Atomically claim promotion. Only one caller can hold the claim at a time; failed receipt persistence resets it (reset_promotion) so promotion can be retried.

pub fn is_promoted(&self) -> bool

True after promotion has completed (receipt persisted), not merely been claimed.

pub fn recover_unsigned( id: String, identity: AgentIdentity, breaker: BreakerConfig, path: PathBuf, metrics: Option<&FinalMetrics>, next_seq: u64, ) -> Result<Self, String>

Recreate a closed unsigned session from a persisted ATIF trajectory.

next_seq is the number of per-session events already published to the bridge for this session (steps ↔ journal records are 1:1, so the step count is exact). Without restoring it, an adopted session reports peek_seq() == 0 and a post-crash SESSION_CLOSE or retroactive-receipt event is minted with metadata.sequence = 0, colliding with the session’s first step event already on the bridge (both sibling recovery paths call restore_next_seq; this one used to be the exception).

pub fn take_trajectory(&self) -> Trajectory

Consume the current ATIF builder and replace it with an empty one.

pub fn atif_steps_count(&self) -> u64

Number of unsigned ATIF steps journaled for this session.

pub async fn wait_for_worker_jobs(&self)

Wait until every accepted worker job for this session has been durably captured (journal fsynced, bridge acked, marker cleared). Public so external harnesses — the criterion bench, embedders sequencing a close after a burst — can drain the audit queue deterministically instead of sleeping.

pub fn active_streams_count(&self) -> u64

Number of forwarded chat responses currently streaming.

pub fn pending_jobs_count(&self) -> u64

Number of worker jobs accepted but not yet fully captured.

pub fn refresh_identity(&self, identity: &AgentIdentity)

Refresh token-derived fields after successful validation.

pub fn current_identity(&self) -> AgentIdentity

Current validated identity snapshot.

pub fn receipt_body( &self, subject: ReceiptSubject, stop: StopReason, ) -> ReceiptBody

Build the receipt body for this session (signed close or promotion).