Invariant

Mental Model ​

Invariant has a small set of primitives that can be combined through a few common execution paths.

Rather than forcing a single rigid static hierarchy, understand how these primitives assemble depending on your execution path and where AI reasoning lives.

Where Does Reasoning Live? ​

Invariant separates orchestration reasoning (deciding what to do next) from task reasoning (answering a bounded question inside an execution):

DimensionAI Agent (app.agent)AI-Assisted Workflow (.reason())
Reasoning FocusOrchestration ReasoningTask Reasoning
Core ResponsibilityAgent owns reasoning; decides what should happen nextWorkflow owns execution; delegates bounded semantic tasks
Trigger MechanismModel turn produces a Runtime Action (start_workflow)Workflow step evaluates a Zod schema result
ScopeApplication & Session surfaceSingle workflow node
text
Invariant Agent (`app.agent`)        External MCP Agent (Cursor / Claude)
──────────────────────────────        ────────────────────────────────────
Internal reasoning model              External reasoning engine
              │                                        │
              └───────────────┐        ┌───────────────┘
                              ▼        ▼
                       Runtime Actions
                              │
                              ▼
                      Durable Workflow

6 Common Execution Paths ​

1. Programmatic Workflow ​

A fully deterministic workflow triggered by an API request, background Cron job, or Stripe webhook. It requires no Agent, no Session, and no LLM calls.

text
REST / Cron / Webhook
        │
        ▼
     Workflow
        │
        ▼
    Execution
        │
        ▼
     Runtime

2. Session-Scoped Workflow ​

A programmatic workflow associated with a long-lived user session (such as tracking an account lifecycle across web or mobile channels) without involving AI reasoning.

text
REST / Webhook
        │
        ▼
     Session
        │
        ▼
     Workflow
        │
        ▼
    Execution
        │
        ▼
     Runtime

3. AI Agent ​

An AI Agent reasons over the workflows it is allowed to drive and fresh Runtime Context. It interprets user intent and proposes constrained Runtime Actions such as starting a workflow or submitting input to an active execution.

text
User Message
      │
      ▼
   Session
      │
      ▼
   AI Agent
      │
      │ Agent Context Projection
      │ (Developer Context + Runtime State + Available Workflows)
      ▼
┌───────────────────────────────┐
│ Available Workflows           │
│ - refund                      │
│ - cancel-subscription         │
│ - update-account              │
│ - support-escalation          │
└───────────────┬───────────────┘
                │
         Runtime Action
                │
                ▼
        Selected Workflow
                │
                ▼
            Execution
                │
                ▼
             Runtime

4. AI-Assisted Workflow ​

A workflow already knows what it is doing, but delegates a bounded semantic question to a model using .reason() alongside deterministic .step() and .capability() nodes.

text
Cron / REST / Event
        │
        ▼
     Workflow
        │
     ├── step()        (deterministic logic)
     ├── reason()      (bounded model reasoning)
     └── capability()  (external side effect)
        │
        ▼
    Execution
        │
        ▼
     Runtime

5. AI Agent over a Persistent Model Session (Live / Realtime) ​

The exact same app.agent() concept as Path 3, but operating over a persistent model session (such as a Gemini Live WebSocket). Following each Runtime Action, the Runtime streams fresh execution projections back to the model in a continuous loop.

text
Live Model Session
        │
        ▼
     Session
        │
        ▼
      Agent
        │
        │ Runtime Projection + available workflows
        ▼
┌───────────────────────────────┐
│ Available Workflows           │
│ - refund                      │
│ - booking                     │
│ - cancel-subscription         │
└───────────────┬───────────────┘
                │
         Runtime Action
                │
                ▼
        Selected Workflow
                │
                ▼
            Execution
                │
                ▼
             Runtime
                │
         next Projection
                ↺

6. External MCP Agent ​

The reasoning engine lives outside Invariant (such as Cursor or Claude Desktop) and interacts via @invariant/mcp. The external client invokes invariant.get_state and issues Runtime Actions against the available workflow surface.

text
External MCP Agent (Cursor / Claude)
        │
        │ invariant.get_state, start_workflow, submit_input
        ▼
   @invariant/mcp
        │
        ▼
     Session
        │
        │ Runtime Projection
        ▼
┌───────────────────────────────┐
│ Relevant Workflows            │
│ - refund                      │
│ - booking                     │
│ - cancellation                │
└───────────────┬───────────────┘
                │
         Runtime Action
                │
                ▼
        Selected Workflow
                │
                ▼
            Execution
                │
                ▼
             Runtime
                │
         next Projection
                ↺

Core Primitives ​

Because relations depend on the execution path, Invariant's primitives remain simple and decoupled:

PrimitiveRole
ApplicationRoot container configuring persistence, models, session context, and adapters.
WorkflowCompiled graph defining allowed execution paths and side-effect boundaries.
ExecutionOne concrete durable run of a Workflow, tracked by a unique runId.
CapabilityThe explicit boundary crossing into external APIs (outbox + retryable).
AgentModel-driven decision layer proposing validated Runtime Actions over available Workflows.
SessionLong-lived continuity boundary for identity, hydrated application context, channels, and related workflow activity. See Sessions & Hydration.
RuntimePure execution kernel ensuring event persistence, state materialization, and crash recovery.

Derived Concepts ​

  • Agent Context Projection — What the Agent needs to know right now. The model-facing view combining developer business context with current execution position, relevant workflows, expected input, and valid actions.
  • Runtime Action — What the Agent is allowed to ask Invariant to do next. A structured request (start_workflow, submit_input, cancel_workflow) proposed by the model and re-validated by the Runtime against fresh durable state.

Core Distinctions ​

text
Workflow ≠ Agent
Workflow ≠ Conversation
Workflow ≠ Session requirement

Workflows define behavior. Executions preserve progress.
Sessions preserve continuity. Executions preserve progress.
Agents may drive Workflows. Workflows do not require Agents.

What the Runtime Guarantees ​

The Runtime owns the mechanics that should not be delegated to a model:

  • Durable State: Maintains the materialized current state of each execution alongside its ordered event history.
  • Ordered Facts: Records execution progress as a monotonic, append-only event log.
  • Atomic Persistence: Commits state transitions and outbox commands within a single database transaction.
  • Outbox Dispatch: Reliably delivers capability requests with at-least-once execution guarantees.
  • Concurrency & Recovery: Serializes concurrent incoming events and resumes suspended executions automatically after worker restart without re-invoking LLMs.

Go Deeper ​

One Sentence per Abstraction ​

Application contains the system.
Workflow defines what may happen.
Execution represents one durable run.
Capability crosses into the external world.
Agent decides what should happen next.
Session preserves continuity when continuity is needed.
Runtime makes execution durable.

Invariant Durable Execution Engine.

Copyright © 2026 Invariant