Sessions

Sessions model multi-round interactions: customer support, voice agents, onboarding flows, or any workflow where progress happens across repeated external signals.

The in-memory runtime lives in bloge-session-ext. Durable checkpointing and recovery live in bloge-session-durable.

Core Concepts

Concept	Meaning
Session	Long-running interaction identified by session identity
Phase	A named stage in the interaction
Round	One execution turn inside a phase
Signal	External input delivered to a suspended session
Snapshot	Immutable view emitted when session state changes

DSL Shape

session customerSupport {
  idle_timeout = 5m
  max_rounds = 20

  phase greeting {
    node greet : SessionGreeter {
      input {
        sessionId = ctx.sessionId
      }
    }
    then -> triage
  }

  phase triage {
    max_rounds = 5
    yield_on = [respond]
    round {
      node respond : SessionResponder {
        input {
          userMessage = ctx.round.input.userMessage
        }
      }
    }
    until respond.output.done == true
    then -> wrapUp
  }
}

Runtime Ownership

bloge-session-ext owns:

• session DSL and compiler
• SessionGraph, PhaseDef, SessionExecutor
• access guards
• timeout policies
• listeners and snapshot callbacks
• session-specific lint rules

It does not own durable checkpoint tables or lease recovery. Those belong to bloge-session-durable.

Durable Sessions

Add bloge-session-durable when sessions must survive process restarts or move between service instances. The durable bridge maps session state onto the generic durable execution/checkpoint stores and handles graph-hash migration.

Use durable sessions when:

• user interactions span minutes, hours, or days
• signals can arrive on different nodes
• session state must be inspectable or recoverable
• graph changes require controlled migration behavior

Design Guidance

• Use a plain graph when the work finishes in one request.
• Use await when one graph needs a small number of external events.
• Use a session when interaction history and repeated rounds are first-class.
• Keep phase transitions explicit; hidden loops make recovery and support harder.
• Add durable sessions before production traffic if sessions cross process lifetimes.