Checkpoints

Checkpoints allow a Devlish program to pause execution and return structured context to its caller. This enables human-in-the-loop review, LLM approval gates, and multi-step workflows that require external input between stages.

Basic Checkpoint

The Checkpoint statement pauses the program and sends a message to the caller:

# Extract and validate data
Read JSON from "application.json" as application
applicant equals name of application
amount equals requested_amount of application

amount must be at least 10000

Checkpoint "Review extracted fields before export"

# This runs only after the caller resumes
Export application to "approved/application.json"

When the VM hits a Checkpoint, it stops and returns the checkpoint message along with the current execution state.

Checkpoint with Context

Save specific variables into the checkpoint payload using saving context as:

Find liability cap and save as liability_cap
Find termination days and save as termination_days

Checkpoint "Approval needed for extracted values" saving context as approval_state

The saved context is included in the checkpoint response, giving the caller visibility into what the program has computed so far.

How the LLM Receives Checkpoints

When running via MCP, a checkpoint produces a structured response:

{
  "success": true,
  "checkpoint": {
    "message": "Review extracted fields before export",
    "context": {
      "applicant": "Acme Corp",
      "amount": 50000
    }
  }
}

The LLM (or human operator) can inspect the context, decide whether to continue, and resume the program.

Resume Semantics

After a checkpoint, the program can be resumed with additional input. The resume provides new values that merge into the program’s context:

devlish run workflow.dvl --input '{"__resume__": true, "approved": true}'

From the MCP layer, the caller invokes the tool again with resume data.

Multi-Stage Workflow Example

# Stage 1: Gather and validate
Read CSV from "invoices.csv" as invoices
total equals reduce invoices starting at 0 with sum and item to sum plus amount of item
invoice_count equals count of invoices

Checkpoint "Review batch before processing" saving context as batch_review

# Stage 2: Process (runs after resume)
For each invoice in invoices:
  Set status of invoice to "processed"

Export invoices to "processed/batch.json"
Respond with record with invoice_count as processed and total as total_value

Use Cases

• Document review: Extract data, pause for human verification, then file
• Approval gates: Compute a result, wait for sign-off, then execute the action
• Progressive disclosure: Show intermediate results to an LLM so it can decide the next step
• Audit trails: Each checkpoint creates a record of what was computed and who approved continuation