State Model

State management in AI agent frameworks is notoriously difficult. Invariant solves this by cleanly separating four distinct types of state:

1. Event Log (workflow_events)

The Event Log is the single source of truth for every workflow run.

• Immutable: Events are append-only. They are never modified or deleted.
• Auditable: Contains every trigger, LLM response payload, tool output, and system error.
• Monotonic: Ordered by integer sequence (seq = 1, 2, 3, ...).

2. Durable Execution State (ExecutionState)

The Durable Execution State represents the accumulated business data for the current workflow run.

• Derived via Reducer: Generated by feeding RuntimeEvents into state-reducer.ts.
• Revision Controlled: Every successful transition increments revision (expectedRevision + 1).
• Conflict Safe: Uses optimistic locking to prevent race conditions across multiple workers.

export interface ExecutionState {
  _context: Record<string, unknown>; // Business variables
  history: Array<{ nodeId: string; timestamp: number }>; // Node execution tracking
}

3. Snapshots & Projections

For fast UI rendering (e.g. chat dashboards, admin tools), Invariant maintains read-optimized projections.

• Non-Blocking: Projections are updated asynchronously or checkpointed during state commits.
• Re-buildable: If a projection table is corrupted or dropped, it can be 100% rebuilt by replaying the Event Log.

4. Ephemeral Model Context (LLM Context)

Passing massive context windows or stale variables into LLMs causes high token costs and prompt confusion. Invariant treats Model Context as Ephemeral:

• Model-Native Routing (v2.1 Pure JSON): Raw JSON payloads (e.g. ui_context) are passed directly to LLM prompts without implicit, rigid TypeScript projections.
• Automatic Loop Cleanup: When a workflow re-enters a looping node (e.g. "Ask -> Answer -> Ask"), Invariant automatically clears ephemeral node outputs before re-entry. This prevents stale LLM outputs from prematurely satisfying edge conditions.

Summary Comparison Table

State Layer	Mutability	Storage Location	Primary Purpose
Event Log	Immutable (Append-only)	workflow_events	Single source of truth & auditing
Execution State	Derived / Versioned	workflow_states	Active business logic variables
Projections	Read-optimized	workflow_projections	Fast UI / Admin query rendering
Model Context	Ephemeral	In-memory during prompt execution	LLM reasoning payload