motionloom 2.6.0 → 2.6.1

package/references/multi-frame-asset-generation.md

@@ -0,0 +1,109 @@
+# Multi-frame asset generation discipline
+
+This contract applies whenever MotionLoom or an Agent creates two or more source frames for the same character, object, effect or other frame-based animation. It is automatic: the user should not have to ask for consistent frame geometry, isolated source frames or atlas hygiene.
+
+## Default source policy
+
+Generated source frames are **isolated-frame assets**, not a pose sheet.
+
+- Generate exactly one animation source frame per image/canvas by default.
+- For long actions (including actions with six or more frames), never ask an image generator for one contact sheet, sprite sheet or multi-pose canvas and then crop the poses out as production source frames.
+- Do not pack an atlas or sprite sheet until every isolated source frame has passed identity and frame-geometry validation.
+- Imported third-party atlases may still use the atlas contract; this rule is about Agent-generated source material.
+
+If a generator cannot preserve isolated source canvases reliably, regenerate in smaller isolated calls or use provider outputs that are already separate files. Do not convert one contaminated multi-pose canvas into accepted source frames merely because crops can be extracted from it.
+
+This avoids neighboring poses leaking into a crop, shared-canvas bleed, accidental partial limbs from adjacent frames and ambiguous ownership of opaque pixels.
+
+## Lock geometry before the second frame
+
+Before generating frame 2, establish one canonical geometry lock from the accepted identity/reference frame and keep it unchanged for the rest of the action:
+
+- exact canvas width and height;
+- transparent alpha mode and color space;
+- camera and left/right orientation;
+- target apparent character scale;
+- pivot point;
+- baseline / footline;
+- safe rectangle and transparent guard band;
+- palette/style/identity reference;
+- frame naming and action order.
+
+Create or update the matching `action-set` and `frame-geometry` contracts before continuing the sequence. The first accepted frame is the geometry anchor; later poses may move limbs, but they must not silently change canvas size, camera, character scale, pivot or baseline.
+
+For AI-generated frames, every subsequent generation request should carry the same locked identity reference and geometry requirements. When the image tool can accept an image reference, reuse the accepted identity/anchor frame rather than relying on prose alone.
+
+## Frame Generation Lock
+
+Do not rely on the Agent remembering the same geometry prose across many provider calls. Persist the generation-side constraints in `frame-generation-lock.json` using `schemas/frame-generation-lock.schema.json`.
+
+The lock binds:
+
+- the exact identity/accepted-frame reference path and SHA-256;
+- canvas dimensions, color space and alpha mode;
+- center, pivot, footline, safe rectangle and minimum transparent padding;
+- target measured alpha-bounds plus permitted width/height drift;
+- appearance features that must be preserved and changes that are forbidden;
+- a hard source policy of one isolated frame per image, no pose sheet and no post-generation resize;
+- every `frame_id`, its pose intent and its unique PNG output path;
+- the post-generation `frame-geometry` contract used by deterministic preflight;
+- a review-only trust boundary with `approval: false`.
+
+Before a provider call, validate the lock and compose the exact frame instruction from it:
+
+```bash
+motionloom frame-generation-lock validate \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --json
+
+motionloom frame-generation-lock compose \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --frame-id <action.frame-id> --json
+```
+
+For batch planning, `compose-all` emits one independent instruction per frame while preserving the same lock hash and reference hash. It does **not** authorize asking a provider for one multi-frame canvas; each returned instruction still represents one isolated source image.
+
+If the reference bytes change, an output path escapes the asset root, two frames target the same PNG, the lock permits a pose sheet/post-resize, or the trust boundary is weakened, validation fails closed before generation.
+
+## Validate incrementally
+
+Do not generate the complete action and only inspect it at the end. After each candidate frame:
+
+1. verify the image is an isolated source canvas rather than a shared pose sheet;
+2. verify exact canvas dimensions and alpha transparency;
+3. measure the real alpha bounding box from pixels;
+4. compare apparent size against the anchor within the declared `bbox_drift_tolerance_px`;
+5. verify pivot and footline tolerance;
+6. verify the alpha bounding box remains inside `safe_rect` with the declared `bleed_margin_px` guard band;
+7. reject unexpected opaque contamination;
+8. only then accept the frame and continue.
+
+Use:
+
+```bash
+motionloom frame-set-preflight \
+  --input src/output/<scene>/<action>-frame-geometry.json \
+  --root src/output/<scene> --json
+```
+
+The preflight is intentionally stricter than a visual warning: shared source images, non-isolated frame rectangles, scale drift beyond the declared tolerance, guard-band violations, pivot/footline drift, hash mismatch or other deterministic frame-geometry failures block the sequence.
+
+If one frame fails, regenerate or repair **that frame only** using the same generation lock. Do not silently rescale every previously accepted frame to match a bad frame, and do not weaken tolerances merely to make the set pass.
+
+## Apparent-size consistency
+
+Equal canvas dimensions are not enough. A 1920 × 1920 PNG can still contain a character that is 20% smaller than the previous frame. MotionLoom therefore treats measured alpha-bounds drift as a real source defect when it exceeds the declared tolerance.
+
+Pose motion can legitimately change the bounding box, so choose a tolerance that allows expected limb extension while preventing whole-character zoom drift. For actions with large reaches, jumps or weapons, lock the body pivot/footline and define a safe rectangle large enough for those poses instead of changing the character scale between frames.
+
+For pixel art, any intentional normalization step must preserve nearest-neighbor pixel density and the locked pivot/baseline. Large scale corrections should trigger regeneration rather than interpolation.
+
+## Packing happens last
+
+Only after every source frame passes preflight may the Agent build a sprite sheet or atlas. The packed result must then pass the atlas contract: no region overlap, no opaque pixels outside declared regions when required, explicit padding/extrusion, and no ambiguous neighboring-frame bleed.
+
+Source-frame acceptance and atlas acceptance are separate gates. A clean atlas cannot repair inconsistent source-frame scale, and consistent source frames do not prove the packed atlas is clean.
+
+## Agent decision rule
+
+When the user asks for an animation such as idle, walk, run, attack, hurt, jump or any project-defined multi-frame action, the Agent should apply this contract automatically. Do not ask the user whether they want frame consistency checks or a generation lock; they are part of the default MotionLoom workflow. Only ask the user when a genuine artistic decision is required, such as choosing between materially different silhouettes or motion intent.

package/schemas/frame-generation-lock.schema.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/frame-generation-lock.schema.json",
+  "title": "MotionLoom Frame Generation Lock",
+  "description": "Provider-neutral, machine-readable generation constraints that keep independently generated animation frames on one identity, canvas and geometry lock before deterministic post-generation preflight.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "lock_id",
+    "asset_identity",
+    "action_id",
+    "reference",
+    "canvas",
+    "geometry",
+    "appearance",
+    "source_policy",
+    "frames",
+    "postflight",
+    "trust"
+  ],
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "lock_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,95}$" },
+    "asset_identity": { "type": "string", "minLength": 1 },
+    "action_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
+    "reference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["image", "sha256", "role"],
+      "properties": {
+        "image": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "role": { "enum": ["identity_anchor", "accepted_frame_anchor"] }
+      }
+    },
+    "canvas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["width", "height", "color_space", "alpha_mode"],
+      "properties": {
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "color_space": { "enum": ["srgb", "linear-srgb"] },
+        "alpha_mode": { "enum": ["straight", "premultiplied"] }
+      }
+    },
+    "geometry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["center_x", "pivot", "footline_px", "safe_rect", "min_padding_px", "target_alpha_bbox", "tolerances"],
+      "properties": {
+        "center_x": { "type": "number" },
+        "pivot": { "$ref": "#/$defs/point" },
+        "footline_px": { "type": "number" },
+        "safe_rect": { "$ref": "#/$defs/rect" },
+        "min_padding_px": { "type": "integer", "minimum": 0 },
+        "target_alpha_bbox": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["width", "height"],
+          "properties": {
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "tolerances": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pivot_px", "footline_px", "bbox_width_px", "bbox_height_px"],
+          "properties": {
+            "pivot_px": { "type": "number", "minimum": 0 },
+            "footline_px": { "type": "number", "minimum": 0 },
+            "bbox_width_px": { "type": "number", "minimum": 0 },
+            "bbox_height_px": { "type": "number", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "appearance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["preserve", "forbid", "pixel_art"],
+      "properties": {
+        "preserve": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "forbid": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "pixel_art": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["enabled", "nearest_neighbor_only"],
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "nearest_neighbor_only": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "source_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["isolated_frames", "max_frames_per_image", "allow_pose_sheet", "allow_post_resize", "reuse_reference"],
+      "properties": {
+        "isolated_frames": { "const": true },
+        "max_frames_per_image": { "const": 1 },
+        "allow_pose_sheet": { "const": false },
+        "allow_post_resize": { "const": false },
+        "reuse_reference": { "const": true }
+      }
+    },
+    "frames": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["frame_id", "pose", "output"],
+        "properties": {
+          "frame_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
+          "pose": { "type": "string", "minLength": 1 },
+          "output": { "type": "string", "pattern": ".+\\.png$" }
+        }
+      }
+    },
+    "postflight": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["frame_geometry"],
+      "properties": {
+        "frame_geometry": { "type": "string", "minLength": 1 }
+      }
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "review_only", "approval"],
+      "properties": {
+        "authority": { "enum": ["ai_generated", "ai_assisted", "code_authored", "unknown"] },
+        "review_only": { "const": true },
+        "approval": { "const": false }
+      }
+    }
+  },
+  "$defs": {
+    "rect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "integer", "minimum": 0 },
+        "y": { "type": "integer", "minimum": 0 },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "point": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "space"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "space": { "enum": ["pixels", "normalized"] }
+      }
+    }
+  }
+}

package/scripts/frame-generation-lock.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Validate and compose provider-neutral instructions from a MotionLoom Frame Generation Lock.
+
+The lock exists to keep independently generated animation frames on one identity,
+canvas and geometry contract before deterministic post-generation preflight. This
+tool does not call an image provider, modify assets, grant provenance authority or
+mint user approval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{1,95}$")
+FRAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{1,63}$")
+SHA_RE = re.compile(r"^[a-f0-9]{64}$")
+
+
+def issue(code: str, message: str, path: str = "") -> dict[str, str]:
+    return {"severity": "error", "code": code, "message": message, "path": path}
+
+
+def load_document(path: Path) -> tuple[dict[str, Any] | None, list[dict[str, str]]]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return None, [issue("invalid_input", str(exc), str(path))]
+    if not isinstance(value, dict):
+        return None, [issue("invalid_document", "lock root must be an object", str(path))]
+    return value, []
+
+
+def inside(root: Path, value: str) -> tuple[Path | None, dict[str, str] | None]:
+    candidate = (root / value).resolve() if not Path(value).is_absolute() else Path(value).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError:
+        return None, issue("path_escape", f"path escapes lock root: {value}", value)
+    return candidate, None
+
+
+def rect_inside(rect: dict[str, Any], width: int, height: int) -> bool:
+    try:
+        x, y = int(rect["x"]), int(rect["y"])
+        w, h = int(rect["width"]), int(rect["height"])
+    except (KeyError, TypeError, ValueError):
+        return False
+    return x >= 0 and y >= 0 and w > 0 and h > 0 and x + w <= width and y + h <= height
+
+
+def validate(document: dict[str, Any], root: Path) -> dict[str, Any]:
+    errors: list[dict[str, str]] = []
+    required = [
+        "schema_version", "lock_id", "asset_identity", "action_id", "reference",
+        "canvas", "geometry", "appearance", "source_policy", "frames", "postflight", "trust",
+    ]
+    for key in required:
+        if key not in document:
+            errors.append(issue("missing_field", f"required field is missing: {key}", key))
+
+    if document.get("schema_version") != "0.1":
+        errors.append(issue("schema_version", "frame generation lock schema_version must be 0.1", "schema_version"))
+    if not ID_RE.match(str(document.get("lock_id", ""))):
+        errors.append(issue("invalid_lock_id", "lock_id must use lowercase safe identifier characters", "lock_id"))
+    if not FRAME_RE.match(str(document.get("action_id", ""))):
+        errors.append(issue("invalid_action_id", "action_id must use lowercase safe identifier characters", "action_id"))
+
+    canvas = document.get("canvas") if isinstance(document.get("canvas"), dict) else {}
+    try:
+        width, height = int(canvas.get("width", 0)), int(canvas.get("height", 0))
+    except (TypeError, ValueError):
+        width, height = 0, 0
+    if width <= 0 or height <= 0:
+        errors.append(issue("invalid_canvas", "canvas width and height must be positive integers", "canvas"))
+    if canvas.get("color_space") not in {"srgb", "linear-srgb"}:
+        errors.append(issue("invalid_color_space", "unsupported canvas color_space", "canvas.color_space"))
+    if canvas.get("alpha_mode") not in {"straight", "premultiplied"}:
+        errors.append(issue("invalid_alpha_mode", "unsupported canvas alpha_mode", "canvas.alpha_mode"))
+
+    reference = document.get("reference") if isinstance(document.get("reference"), dict) else {}
+    ref_value = str(reference.get("image", ""))
+    ref_path, path_error = inside(root, ref_value) if ref_value else (None, issue("missing_reference", "reference.image is required", "reference.image"))
+    if path_error:
+        errors.append(path_error)
+    expected_hash = str(reference.get("sha256", ""))
+    if not SHA_RE.match(expected_hash):
+        errors.append(issue("invalid_reference_sha256", "reference.sha256 must be 64 lowercase hex characters", "reference.sha256"))
+    if ref_path is not None:
+        try:
+            actual_hash = hashlib.sha256(ref_path.read_bytes()).hexdigest()
+        except OSError as exc:
+            errors.append(issue("reference_unreadable", str(exc), "reference.image"))
+        else:
+            if expected_hash and actual_hash != expected_hash:
+                errors.append(issue("reference_sha256_mismatch", "reference bytes do not match the locked SHA-256", "reference.sha256"))
+    if reference.get("role") not in {"identity_anchor", "accepted_frame_anchor"}:
+        errors.append(issue("invalid_reference_role", "reference.role must be identity_anchor or accepted_frame_anchor", "reference.role"))
+
+    geometry = document.get("geometry") if isinstance(document.get("geometry"), dict) else {}
+    safe_rect = geometry.get("safe_rect") if isinstance(geometry.get("safe_rect"), dict) else {}
+    if width > 0 and height > 0 and not rect_inside(safe_rect, width, height):
+        errors.append(issue("invalid_safe_rect", "geometry.safe_rect must fit inside the locked canvas", "geometry.safe_rect"))
+    target = geometry.get("target_alpha_bbox") if isinstance(geometry.get("target_alpha_bbox"), dict) else {}
+    try:
+        target_w, target_h = int(target.get("width", 0)), int(target.get("height", 0))
+    except (TypeError, ValueError):
+        target_w, target_h = 0, 0
+    if target_w <= 0 or target_h <= 0 or (width > 0 and target_w > width) or (height > 0 and target_h > height):
+        errors.append(issue("invalid_target_bbox", "target alpha bbox must be positive and fit inside the canvas", "geometry.target_alpha_bbox"))
+    try:
+        min_padding = int(geometry.get("min_padding_px", -1))
+    except (TypeError, ValueError):
+        min_padding = -1
+    if min_padding < 0:
+        errors.append(issue("invalid_padding", "geometry.min_padding_px must be non-negative", "geometry.min_padding_px"))
+    tolerances = geometry.get("tolerances") if isinstance(geometry.get("tolerances"), dict) else {}
+    for key in ("pivot_px", "footline_px", "bbox_width_px", "bbox_height_px"):
+        try:
+            value = float(tolerances.get(key, -1))
+        except (TypeError, ValueError):
+            value = -1
+        if value < 0:
+            errors.append(issue("invalid_tolerance", f"geometry.tolerances.{key} must be non-negative", f"geometry.tolerances.{key}"))
+
+    source = document.get("source_policy") if isinstance(document.get("source_policy"), dict) else {}
+    expected_source = {
+        "isolated_frames": True,
+        "max_frames_per_image": 1,
+        "allow_pose_sheet": False,
+        "allow_post_resize": False,
+        "reuse_reference": True,
+    }
+    for key, expected in expected_source.items():
+        if source.get(key) != expected:
+            errors.append(issue("unsafe_source_policy", f"source_policy.{key} must be {expected!r}", f"source_policy.{key}"))
+
+    appearance = document.get("appearance") if isinstance(document.get("appearance"), dict) else {}
+    for key in ("preserve", "forbid"):
+        values = appearance.get(key)
+        if not isinstance(values, list) or not values or any(not isinstance(value, str) or not value.strip() for value in values):
+            errors.append(issue("invalid_appearance_rule", f"appearance.{key} must be a non-empty string array", f"appearance.{key}"))
+    pixel_art = appearance.get("pixel_art") if isinstance(appearance.get("pixel_art"), dict) else {}
+    if pixel_art.get("enabled") is True and pixel_art.get("nearest_neighbor_only") is not True:
+        errors.append(issue("unsafe_pixel_art_policy", "pixel-art locks require nearest_neighbor_only=true", "appearance.pixel_art.nearest_neighbor_only"))
+
+    frames = document.get("frames") if isinstance(document.get("frames"), list) else []
+    if len(frames) < 2:
+        errors.append(issue("insufficient_frames", "a frame generation lock requires at least two frames", "frames"))
+    seen_ids: set[str] = set()
+    seen_outputs: set[str] = set()
+    for index, frame in enumerate(frames):
+        prefix = f"frames[{index}]"
+        if not isinstance(frame, dict):
+            errors.append(issue("invalid_frame", "frame must be an object", prefix))
+            continue
+        frame_id = str(frame.get("frame_id", ""))
+        if not FRAME_RE.match(frame_id):
+            errors.append(issue("invalid_frame_id", "frame_id must use lowercase safe identifier characters", f"{prefix}.frame_id"))
+        if frame_id in seen_ids:
+            errors.append(issue("duplicate_frame_id", f"duplicate frame_id: {frame_id}", f"{prefix}.frame_id"))
+        seen_ids.add(frame_id)
+        if not str(frame.get("pose", "")).strip():
+            errors.append(issue("missing_pose", "frame pose instruction is required", f"{prefix}.pose"))
+        output = str(frame.get("output", ""))
+        if not output.lower().endswith(".png"):
+            errors.append(issue("invalid_output", "frame output must be a PNG path", f"{prefix}.output"))
+        if output in seen_outputs:
+            errors.append(issue("duplicate_output", f"multiple frames target the same output: {output}", f"{prefix}.output"))
+        seen_outputs.add(output)
+        _, output_error = inside(root, output) if output else (None, issue("invalid_output", "frame output is required", f"{prefix}.output"))
+        if output_error:
+            output_error["path"] = f"{prefix}.output"
+            errors.append(output_error)
+
+    postflight = document.get("postflight") if isinstance(document.get("postflight"), dict) else {}
+    geometry_value = str(postflight.get("frame_geometry", ""))
+    _, geometry_error = inside(root, geometry_value) if geometry_value else (None, issue("missing_postflight", "postflight.frame_geometry is required", "postflight.frame_geometry"))
+    if geometry_error:
+        geometry_error["path"] = "postflight.frame_geometry"
+        errors.append(geometry_error)
+
+    trust = document.get("trust") if isinstance(document.get("trust"), dict) else {}
+    if trust.get("review_only") is not True or trust.get("approval") is not False:
+        errors.append(issue("invalid_trust_boundary", "generation locks must remain review_only with approval=false", "trust"))
+    if trust.get("authority") not in {"ai_generated", "ai_assisted", "code_authored", "unknown"}:
+        errors.append(issue("invalid_authority", "unsupported trust.authority", "trust.authority"))
+
+    canonical = json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    return {
+        "contract": "frame_generation_lock",
+        "ready": not errors,
+        "errors": errors,
+        "warnings": [],
+        "metrics": {
+            "frame_count": len(frames),
+            "canvas": {"width": width, "height": height},
+            "lock_sha256": hashlib.sha256(canonical).hexdigest(),
+            "reference_sha256": expected_hash or None,
+            "isolated_frames": source.get("isolated_frames") is True,
+        },
+        "approval": False,
+    }
+
+
+def find_frame(document: dict[str, Any], frame_id: str) -> dict[str, Any] | None:
+    for frame in document.get("frames", []):
+        if isinstance(frame, dict) and frame.get("frame_id") == frame_id:
+            return frame
+    return None
+
+
+def compose_instruction(document: dict[str, Any], frame: dict[str, Any]) -> str:
+    canvas = document["canvas"]
+    geometry = document["geometry"]
+    appearance = document["appearance"]
+    reference = document["reference"]
+    target = geometry["target_alpha_bbox"]
+    tolerances = geometry["tolerances"]
+    safe = geometry["safe_rect"]
+    pivot = geometry["pivot"]
+    preserve = "; ".join(str(value).strip() for value in appearance["preserve"])
+    forbid = "; ".join(str(value).strip() for value in appearance["forbid"])
+    pixel_rule = " Use crisp nearest-neighbor pixel edges; do not resample or blur." if appearance.get("pixel_art", {}).get("enabled") else ""
+    return (
+        f"MotionLoom Frame Generation Lock {document['lock_id']} for action {document['action_id']}. "
+        f"Use reference image {reference['image']} as the locked {reference['role']} with SHA-256 {reference['sha256']}. "
+        f"Generate exactly ONE isolated source frame for {frame['frame_id']}; never create a pose sheet, contact sheet, collage, atlas, or multiple poses in one image. "
+        f"Pose: {frame['pose']} "
+        f"Canvas is exactly {canvas['width']} × {canvas['height']} pixels, {canvas['color_space']} with {canvas['alpha_mode']} alpha. "
+        f"Keep the subject centered near x={geometry['center_x']}; pivot={pivot['x']},{pivot['y']} ({pivot['space']}); footline={geometry['footline_px']} px. "
+        f"Keep all opaque pixels inside safe rect x={safe['x']}, y={safe['y']}, width={safe['width']}, height={safe['height']} and preserve at least {geometry['min_padding_px']} px transparent padding. "
+        f"Target apparent alpha bounds are approximately {target['width']} × {target['height']} px; do not introduce whole-subject zoom drift beyond ±{tolerances['bbox_width_px']} px width or ±{tolerances['bbox_height_px']} px height, pivot drift beyond ±{tolerances['pivot_px']} px, or footline drift beyond ±{tolerances['footline_px']} px. "
+        f"Preserve: {preserve}. Forbid: {forbid}.{pixel_rule} "
+        f"Do not mirror, crop from a shared canvas, silently change camera/scale, or resize the generated frame afterward. "
+        f"Return/save only the single PNG as {frame['output']}. This is review evidence only; generation success does not imply artist authorship, production eligibility, runtime approval, licence, or user approval."
+    )
+
+
+def compose(document: dict[str, Any], root: Path, frame_id: str | None = None) -> dict[str, Any]:
+    validation = validate(document, root)
+    if not validation["ready"]:
+        return validation
+    frames = document["frames"] if frame_id is None else [find_frame(document, frame_id)]
+    if frame_id is not None and frames[0] is None:
+        return {
+            "contract": "frame_generation_lock",
+            "ready": False,
+            "errors": [issue("unknown_frame", f"frame_id not found in lock: {frame_id}", "frame_id")],
+            "warnings": [],
+            "metrics": validation["metrics"],
+            "approval": False,
+        }
+    postflight = document["postflight"]["frame_geometry"]
+    items = [
+        {
+            "frame_id": frame["frame_id"],
+            "output": frame["output"],
+            "instruction": compose_instruction(document, frame),
+        }
+        for frame in frames
+        if isinstance(frame, dict)
+    ]
+    return {
+        "contract": "frame_generation_lock",
+        "ready": True,
+        "lock_id": document["lock_id"],
+        "action_id": document["action_id"],
+        "lock_sha256": validation["metrics"]["lock_sha256"],
+        "reference_sha256": validation["metrics"]["reference_sha256"],
+        "frames": items,
+        "next_gate": f"motionloom frame-set-preflight --input {postflight} --root {root} --json",
+        "approval": False,
+    }
+
+
+def emit(result: dict[str, Any], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+    if not result.get("ready"):
+        print("frame generation lock: FAIL")
+        for item in result.get("errors", []):
+            print(f"ERROR {item.get('code')}: {item.get('message')}")
+        return
+    if "frames" not in result:
+        print("frame generation lock: PASS")
+        return
+    for frame in result["frames"]:
+        print(frame["instruction"])
+        print()
+    print(f"Next gate: {result['next_gate']}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("validate", "compose", "compose-all"):
+        command = sub.add_parser(name)
+        command.add_argument("--input", required=True, help="frame-generation-lock JSON")
+        command.add_argument("--root", default=".", help="project/asset root used to resolve paths")
+        command.add_argument("--json", action="store_true", dest="as_json")
+        if name == "compose":
+            command.add_argument("--frame-id", required=True)
+    args = parser.parse_args(argv)
+    document, load_errors = load_document(Path(args.input))
+    if load_errors or document is None:
+        result = {"contract": "frame_generation_lock", "ready": False, "errors": load_errors, "warnings": [], "metrics": {}, "approval": False}
+    else:
+        root = Path(args.root).resolve()
+        if args.command == "validate":
+            result = validate(document, root)
+        elif args.command == "compose":
+            result = compose(document, root, args.frame_id)
+        else:
+            result = compose(document, root)
+    emit(result, args.as_json)
+    return 0 if result.get("ready") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())