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 Agent through a Custom MCP Bridge ​

The reasoning engine can live outside Invariant. In the current Beta, applications build this bridge with @modelcontextprotocol/sdk; the planned @invariant-tech/mcp package is not released.

text
External MCP Agent (Cursor / Claude)
        │
        │ invariant.get_state, start_workflow, submit_input
        ▼
 Application-owned MCP bridge
        │
        ▼
     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 (stored command intent + stable idempotency identity).
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.
ProjectionPure, typed, read-only view deriving what a specific consumer or channel sees from durable truth. See Projections.
RuntimePure execution kernel deriving transitions that a store commits atomically.

Derived Concepts ​

  • Runtime Projection — What Invariant knows about execution. The runtime-generated truth containing active workflow, current node, valid actions, expected input, revision, and status.
  • Application Projection (app.projection) — What a consumer needs to see. Developer-defined pure transformations for Voice (Gemini Live), UI widgets (SSE), 3D scenes (Tarot), or custom APIs.
  • 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.
Projections interpret truth. The Runtime owns truth.
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.
  • Current Dispatch: Session drains committed commands in process. Request-driven .wait() reattachment is public through Session restoration; cross-process command claim and work redispatch are not.
  • Concurrency & Recovery Primitives: OCC serializes competing commits; stores expose leases and runnable-run discovery. These are prerequisites, not an automatic recovery host.

Go Deeper ​

The Four Symmetrical Boundaries ​

Invariant is an Execution Control Plane for probabilistic software. It applies proven distributed systems mechanisms around the boundary where AI reasoning proposes actions:

text
External World
      │
      ▼
   ADMIT       ──► Knowledge / Ingestion Boundary (Hydration)
 (Hydration)       "What external facts are admitted into runtime context?"
      │
      ▼
 Durable Truth ──► PostgreSQL Event Sourcing + Monotonic State
      │
      ▼
   EXPOSE      ──► Projection Boundary (app.projection)
 (Projection)      "What may this consumer (Voice/UI/Agent/MCP) observe?"
      │
      ▼
Probabilistic Model (LLM / Gemini Live / Claude)
      │
      ▼
   PROPOSE     ──► Authority Boundary (Runtime Actions & validActions)
 (Action Prop)     "What may this consumer or model propose next?"
      │
      ▼
  VALIDATE     ──► Schema Gate + Fresh validActions + Wait Boundary OCC
      │
      ├──── [Rejection] ──► 400 Error / Unvalidated input NEVER becomes history
      │
      ▼
   COMMIT      ──► Execution Boundary (Pure Kernel Transition)
(Durable Exec)     "What may become authoritative progress?"
      │
      ▼
   EFFECT      ──► Transactional Outbox + Stable Idempotency Keys
(Capabilities)     "What side-effects are dispatched to the external world?"
      │
      ▼
External World ──► lifecycle.cancel (Durable compensation when needed)

$$\text{ADMIT} \longrightarrow \text{EXPOSE} \longrightarrow \text{PROPOSE} \longrightarrow \text{COMMIT} \longrightarrow \text{EFFECT}$$

BoundaryPrimitiveCore Question
1. Knowledge / IngestionHydration & Session ContextWhat external facts are admitted into runtime context?
2. Projectionapp.projection()What may this consumer or model observe? (Context minimization, PII redaction)
3. AuthorityRuntime Actions & validActionsWhat may this consumer or model propose next? (fresh action-surface and wait-boundary validation)
4. ExecutionWorkflows & PostgreSQL KernelWhat may become authoritative progress and committed state?
→ EffectCapabilities & OutboxWhat side-effects are delivered to external systems? (Idempotent delivery & lifecycle.cancel compensation)

Built on Proven Systems Engineering ​

Invariant did not reinvent distributed systems. It asks a specific question:

What should application architecture look like when part of its reasoning is delegated to a probabilistic model?

Event sourcing, optimistic concurrency control, idempotency, transactional outboxes, durable state machines, retries, and compensation are lessons the software industry has developed over decades. Invariant organizes those proven guarantees around a new primitive: a probabilistic reasoner that may propose what happens next, but does not own the authority to make it true.

Three Starting Assumptions ​

ParadigmComputational PremiseExecution Relationship
Traditional Workflows (Temporal, Cadence)Deterministic program logicProgram code $\longrightarrow$ Reliable execution
Agent Frameworks (LangChain, CrewAI)Autonomous model driving toolsModel $\longrightarrow$ Tools $\longrightarrow$ In-memory loop
Invariant Control PlaneProbabilistic reasoning requiring explicit authority boundariesModel (Proposes) $\longrightarrow$ Authority Boundary (Validates) $\longrightarrow$ Durable Execution

One Sentence per Abstraction ​

Application contains the system.
Workflow defines what may happen.
Agent decides what should happen.
Session carries continuity forward.
Projection decides what a consumer sees.
Capability touches the outside world.
Execution represents one durable run.
Runtime commits execution truth; a configured durable store preserves it.

The runtime owns truth. Projections control exposure. Runtime Actions control authority. Capabilities deliver effects.

Invariant Durable Execution Engine.

Copyright © 2026 Invariant