# OpenMontage Checkpoint Protocol: How It Enables Pipeline Resumption

> Discover OpenMontage's checkpoint protocol, a JSON snapshot system that records pipeline state for automatic resumption after failures. Ensure smooth workflows and audit trails.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: internals
- Published: 2026-08-30

---

**OpenMontage's checkpoint protocol is a lightweight, JSON-based snapshot mechanism defined in [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py) that records complete pipeline state after each stage finishes, enabling automatic resumption from failures while enforcing human approval gates and maintaining full audit trails.**

OpenMontage is an open-source video production framework that orchestrates complex, multi-stage AI pipelines. The **checkpoint protocol** provides the foundation for fault-tolerant execution by persisting stage states to disk, allowing interrupted workflows to resume exactly where they left off without data loss or duplication of work.

## What Is the OpenMontage Checkpoint Protocol?

The checkpoint protocol in OpenMontage is implemented in [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py) and enforced by the JSON Schema defined in [`schemas/checkpoints/checkpoint.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/schemas/checkpoints/checkpoint.schema.json). It creates atomic snapshots of pipeline state that capture everything needed to reconstruct the current execution context.

### Schema Structure and Required Fields

Each checkpoint file stores the following structured data:

| Field | Purpose |
|-------|---------|
| `version` | Protocol version (`"1.0"`). |
| `project_id` | Unique identifier for the project. |
| `pipeline_type` | Name of the pipeline manifest (e.g., `"explainer"`). |
| `stage` | The stage the checkpoint represents (validated against the pipeline manifest). |
| `status` | One of `completed`, `failed`, `awaiting_human`, or `in_progress`. |
| `timestamp` | ISO-8601 UTC time when the checkpoint was written. |
| `artifacts` | Map of artifact names to data or file paths (e.g., `render_report`, `proposal_packet`). |
| `human_approval_required` / `human_approved` | Gate-enforcement flags ensuring stages cannot be marked `completed` without explicit human sign-off when required. |
| Optional fields (`style_playbook`, `review`, `cost_snapshot`, `error`, `metadata`) | Extra context used by downstream tools. |

This schema ensures that every checkpoint contains sufficient metadata for the orchestrator to validate state consistency before proceeding to subsequent stages.

## How the Checkpoint Protocol Facilitates Pipeline Resumption

The protocol enables robust pipeline resumption through five key mechanisms that work together to guarantee data integrity and execution continuity.

### Deterministic Stage Progression

The function `get_pipeline_stages(pipeline_type)` returns the canonical execution order defined in the pipeline manifest. When a stage finishes successfully, `write_checkpoint` persists the state to disk using atomic file operations. This deterministic ordering ensures that resumption always follows the intended sequence, even after unexpected interruptions.

### State Validation and Artifact Verification

Before any checkpoint is accepted, the `validate_checkpoint` function verifies the JSON Schema compliance and calls `_validate_artifacts_for_stage` to confirm that all required canonical artifacts are present. This validation guarantees that a resumed run encounters a consistent, well-formed state, preventing partial or corrupted executions from propagating through the pipeline.

### Automatic Archival for Auditability

The protocol maintains complete execution history through the `_archive_superseded_checkpoint` function. Before overwriting an existing checkpoint, the system copies the previous version into a `history/` directory with timestamped filenames. This archival strategy preserves a full audit trail and enables replay of any previous pipeline state for debugging or compliance purposes.

### Human Gate Enforcement

Critical stages can require explicit human approval through the `human_approval_required` flag. The protocol enforces that `completed` status cannot be written unless `human_approved` is explicitly set to true. This gate mechanism prevents automated processes from proceeding past human-in-the-loop checkpoints without proper authorization, ensuring quality control even across resumption scenarios.

### Resumption Logic and Next Stage Computation

The protocol provides helper functions `read_checkpoint` and `get_latest_checkpoint` to retrieve the most recent valid state. The `get_next_stage` function compares the current checkpoint against the pipeline manifest to determine the next uncompleted stage. When a pipeline restarts, the orchestrator simply reads the latest checkpoint, validates it, and continues execution from the computed next stage, seamlessly handling both crashes and intentional pauses.

## Working with Checkpoints in Practice

The [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py) module provides a Python API for interacting with the checkpoint protocol. Below are practical implementations of common operations.

### Initialize a New Project

Use `init_project` to create the canonical directory structure and initial metadata:

```python
from pathlib import Path
from lib.checkpoint import init_project

project_dir = init_project(
    project_id="proj123",
    title="My Explainer Video",
    pipeline_type="explainer",          # matches a manifest in `pipeline_defs/`

    style_playbook="modern",            # optional visual-style reference

    pipeline_dir=Path("/mnt/projects")  # defaults to the global PROJECTS_DIR

)
print(project_dir)  # → /mnt/projects/proj123

```

This function creates the project directory layout and writes [`project.json`](https://github.com/calesthio/OpenMontage/blob/main/project.json), the marker file used by the Backlot watcher to track active pipelines.

### Write a Checkpoint After Stage Completion

After processing a stage, persist the state using `write_checkpoint`:

```python
from lib.checkpoint import write_checkpoint

checkpoint_path = write_checkpoint(
    pipeline_dir=Path("/mnt/projects"),
    project_id="proj123",
    stage="compose",
    status="completed",
    artifacts={
        "render_report": {"video_path": "renders/final.mp4"},
        "decision_log": {"decisions": []}
    },
    pipeline_type="explainer",
    human_approval_required=True,
    human_approved=True                 # required because the stage gates on approval

)
print(checkpoint_path)  # → /mnt/projects/proj123/checkpoint_compose.json

```

The call validates the checkpoint against the schema, archives any previous version via `_archive_superseded_checkpoint`, and writes the new file atomically to prevent corruption during write operations.

### Resume a Pipeline After Interruption

To resume execution after a crash or pause, use `get_next_stage` to determine where to continue:

```python
from lib.checkpoint import get_next_stage, read_checkpoint

# Load the most recent checkpoint (optional, for inspection)

last_cp = read_checkpoint(Path("/mnt/projects"), "proj123", "compose")
print(last_cp["status"])  # → "completed"

# Determine which stage to run next

next_stage = get_next_stage(Path("/mnt/projects"), "proj123", pipeline_type="explainer")
print(next_stage)  # → "publish" (or None if pipeline is finished)

```

The `get_next_stage` function automatically skips completed stages according to the pipeline manifest order, ensuring that resumption always occurs at the correct execution point.

### Access Historical Checkpoint Data

Archived checkpoints remain accessible for audit or rollback purposes:

```python
from pathlib import Path
from lib.checkpoint import read_checkpoint

# The historic file lives under the `history/` subdirectory:

historic_path = Path("/mnt/projects/proj123/history/checkpoint_compose_20241012T083000Z.json")
historic_cp = read_checkpoint(Path("/mnt/projects"), "proj123", "compose")

# `read_checkpoint` works for any valid checkpoint path, making replay possible.

```

Archived checkpoints conform to the same schema as current checkpoints, allowing them to be re-validated and inspected using standard protocol functions.

## Summary

The OpenMontage checkpoint protocol provides robust fault tolerance for AI video pipelines through these key capabilities:

- **JSON-based state snapshots** that capture complete stage context, artifacts, and metadata in [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py)
- **Schema validation** enforced by [`schemas/checkpoints/checkpoint.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/schemas/checkpoints/checkpoint.schema.json) to guarantee data integrity
- **Automatic archival** to `history/` directories for complete audit trails and rollback capability
- **Human gate enforcement** via `human_approved` flags that prevent unauthorized stage completion
- **Deterministic resumption** using `get_next_stage` to compute the correct restart point from `checkpoint_*.json` files

Together, these features ensure that OpenMontage pipelines can survive interruptions, maintain compliance, and resume execution without manual intervention or data loss.

## Frequently Asked Questions

### What file format does OpenMontage use for checkpoints?

OpenMontage uses JSON files for all checkpoints, with a strict schema defined in [`schemas/checkpoints/checkpoint.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/schemas/checkpoints/checkpoint.schema.json). Each checkpoint file follows the naming convention `checkpoint_{stage}.json` and contains fields for version, status, artifacts, and human approval flags. The JSON format enables human-readable state inspection while supporting atomic write operations for data safety.

### How does OpenMontage validate checkpoint integrity?

The protocol validates checkpoints through the `validate_checkpoint` function, which enforces JSON Schema compliance and verifies that all required artifacts for the current stage are present via `_validate_artifacts_for_stage`. This dual validation ensures that resumed pipelines only proceed from consistent, complete states, preventing corruption from partial writes or missing dependencies.

### Can I resume a pipeline from a specific historical checkpoint?

Yes. The `_archive_superseded_checkpoint` function preserves previous states in the `history/` directory with timestamped filenames. You can point `read_checkpoint` directly at any archived checkpoint file to inspect or replay that specific state. This capability supports rollback scenarios and debugging by allowing operators to restart from any previous valid state rather than only the most recent one.

### What happens if a stage requires human approval?

When `human_approval_required` is set to true in a checkpoint, the protocol enforces that `human_approved` must also be true before the stage can be marked as `completed`. The `write_checkpoint` function will reject attempts to write a completed status without the approval flag, effectively creating a hard gate that pauses pipeline execution until explicit human authorization is recorded in the checkpoint file.