OpenMontage Checkpoint Protocol: How It Enables Pipeline Resumption

OpenMontage's checkpoint protocol is a lightweight, JSON-based snapshot mechanism defined in 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 and enforced by the JSON Schema defined in 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 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:

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, 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:

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:

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:

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
• Schema validation enforced by 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}