# How OpenMontage Enforces the Delivery Promise and Prevents Motion-Led Violations

> OpenMontage ensures delivery promises and prevents motion-led violations with its three-stage validation system. Detects and blocks rendering errors early.

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

---

**OpenMontage enforces delivery promises through a three-stage validation system that classifies content types, validates cuts against minimum motion ratios, and blocks rendering at the pre-compose stage if violations are detected.**

The calesthio/OpenMontage repository implements a rigorous **delivery promise** framework to ensure that video compositions meet their contractual motion requirements. By centralizing promise rules in a declarative table and enforcing them immediately before rendering, the system prevents silent downgrades from motion-led to still-led outputs.

## The Three-Stage Enforcement Architecture

OpenMontage safeguards commitments through a strict validation pipeline built around the **DeliveryPromise** model. This architecture ensures that a motion-led brief cannot silently revert to a still-led output by enforcing constraints at classification, validation, and pre-render stages.

### Promise Classification and Rule Definition

When a proposal is created, the system constructs a `DeliveryPromise` object that records the intended delivery type, motion requirements, and allowed fallbacks. According to the source code in [`lib/delivery_promise.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/delivery_promise.py), this model defines a `PromiseType` enum together with a `PROMISE_RULES` map that encodes per-type constraints.

The rule table specifies:
- **`still_fallback_allowed`** – Whether a still-led fallback can be used
- **`requires_video_generation`** – Whether video generation is mandatory
- **`min_motion_ratio`** – The minimum proportion of real-motion cuts (≥70% for pure motion-led briefs)

### Runtime Cut Classification and Motion Ratio Calculation

The `validate_cuts()` method evaluates each cut against the promise rules. As implemented in [`lib/delivery_promise.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/delivery_promise.py), this method classifies content into three strict categories:

- **Real motion**: `video`, `animation`, or `avatar` content
- **Slide-grammar**: Remotion-style text or chart slides
- **Still**: Static image content

The system computes the **motion ratio** by dividing the count of real-motion cuts by the total number of cuts. If the ratio falls below the `min_motion_ratio` threshold defined in `PROMISE_RULES`, or if non-motion fallbacks are used when `still_fallback_allowed` is false, the method raises a violation.

### Pre-Compose Gatekeeping to Block Violations

The validation is invoked in the `_pre_compose_validation` routine of [`tools/video/video_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_compose.py). This function extracts the serialized `delivery_promise` from `edit_decisions`, reconstructs a `DeliveryPromise` via `DeliveryPromise.from_dict()`, and executes `validate_cuts(resolved_cuts)`.

If violations are detected, the compose step aborts immediately and returns a `ToolResult` with `success=False` containing detailed error messages. This gatekeeping guarantees that rendering never proceeds when motion-led violations are present. Complementary risk scoring from [`lib/slideshow_risk.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/slideshow_risk.py) operates alongside this check in the same validation gate.

## Implementing Delivery Promise Validation

The validation workflow involves constructing a promise object and verifying cuts before composition.

### Creating a Motion-Led Delivery Promise

To define a pure-motion cinematic brief, instantiate the `DeliveryPromise` class with the appropriate `PromiseType`:

```python
from lib.delivery_promise import DeliveryPromise, PromiseType

# Build a delivery promise for a pure-motion cinematic brief

promise = DeliveryPromise(
    promise_type=PromiseType.MOTION_LED,
    motion_required=True,
    source_required=False,
    tone_mode="cinematic",
    quality_floor="broadcast",
)

```

### Validating Cuts Against Motion Constraints

After the edit-decision stage produces cuts, validate them against the promise rules:

```python

# Simulate cuts produced by the edit-decision stage

cuts = [
    {"source": "clip1.mp4", "type": "video"},
    {"source": "slide1.png", "type": "text_card"},
    {"source": "animation1.gif", "type": "animation"},
]

# Validate – this fails because slide-grammar does not count as motion

result = promise.validate_cuts(cuts)
print(result["valid"])      # → False

print(result["violations"]) # → ["Motion ratio 33% is below minimum 70% …"]

```

### Integration in the Composition Pipeline

The `_pre_compose_validation` function in [`tools/video/video_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_compose.py) integrates this check into the rendering pipeline:

```python

# Inside the compose tool (simplified)

from lib.delivery_promise import DeliveryPromise

def _pre_compose_validation(edit_decisions, resolved_cuts):
    delivery_data = edit_decisions.get("delivery_promise")
    if delivery_data:
        promise = DeliveryPromise.from_dict(delivery_data)
        validation = promise.validate_cuts(resolved_cuts)
        if not validation["valid"]:
            raise RuntimeError(
                "Delivery promise violation: " + "; ".join(validation["violations"])
            )
    # …continue with rendering if no violations

```

The [`tests/eval/bench_runner.py`](https://github.com/calesthio/OpenMontage/blob/main/tests/eval/bench_runner.py) harness provides comprehensive testing coverage for this validation logic, ensuring the classifier blocks non-compliant compositions as expected.

## Summary

- **Centralized Rules**: The `PROMISE_RULES` table in [`lib/delivery_promise.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/delivery_promise.py) declares constraints like `min_motion_ratio` and `still_fallback_allowed` for each `PromiseType`.
- **Strict Validation**: The `validate_cuts()` method computes motion ratios and rejects cuts that breach minimum thresholds or fallback restrictions.
- **Render Blocking**: The `_pre_compose_validation` gate in [`tools/video/video_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_compose.py) aborts composition and returns `success=False` before any rendering occurs.
- **Violation Transparency**: Users receive detailed error messages specifying exactly which constraints were breached and which cuts caused the violation.

## Frequently Asked Questions

### What happens when a delivery promise violation is detected?

When `validate_cuts()` detects a violation, the `_pre_compose_validation` routine raises a `RuntimeError` with a detailed message listing the specific breaches. The composition aborts immediately, returning a `ToolResult` with `success=False` to prevent any rendering of non-compliant content.

### How does OpenMontage classify different cut types for validation?

The system categorizes cuts into three types: **real motion** (video, animation, avatar), **slide-grammar** (Remotion-style text or chart slides), and **still** content. Only real motion cuts count toward the motion ratio calculation, ensuring that slide-based fallbacks cannot satisfy motion-led requirements.

### Where in the pipeline does delivery promise validation occur?

Validation occurs in the **pre-compose stage** within [`tools/video/video_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_compose.py). The `_pre_compose_validation` function extracts the promise from `edit_decisions`, reconstructs the `DeliveryPromise` object, and validates the resolved cuts before any video generation begins.

### Can the minimum motion ratio be customized for different brief types?

Yes. The `min_motion_ratio` constraint is defined per promise type in the `PROMISE_RULES` map within [`lib/delivery_promise.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/delivery_promise.py). Different `PromiseType` values can specify different thresholds (e.g., 70% for pure motion-led, lower ratios for mixed formats), allowing flexible yet enforceable constraints.