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

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

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:

# 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 integrates this check into the rendering pipeline:

# 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 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 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 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. 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. Different PromiseType values can specify different thresholds (e.g., 70% for pure motion-led, lower ratios for mixed formats), allowing flexible yet enforceable constraints.

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