motionloom 2.6.0 → 2.6.1

package/scripts/frame-set-preflight.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Fail-closed preflight for Agent-generated multi-frame source assets.
+
+This wrapper reuses MotionLoom's deterministic frame-geometry measurements, then
+adds generation-time rules that are intentionally stricter than a generic asset
+inspection: source frames must be isolated canvases, scale drift is blocking,
+and the measured alpha bounds must preserve the declared transparent guard band.
+
+It never grants provenance authority, artistic approval or production approval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+ASSET_CONSISTENCY = ROOT / "scripts" / "asset-consistency.py"
+
+
+def load_asset_consistency():
+    spec = importlib.util.spec_from_file_location("motionloom_asset_consistency", ASSET_CONSISTENCY)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load asset-consistency.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+AC = load_asset_consistency()
+
+
+def _error(code: str, message: str, path: str = "") -> dict[str, str]:
+    return {"severity": "error", "code": code, "message": message, "path": path}
+
+
+def _normalise_rect(value: dict[str, Any]) -> dict[str, int]:
+    return {key: int(value[key]) for key in ("x", "y", "width", "height")}
+
+
+def _contains(outer: dict[str, int], inner: dict[str, int]) -> bool:
+    return (
+        inner["x"] >= outer["x"]
+        and inner["y"] >= outer["y"]
+        and inner["x"] + inner["width"] <= outer["x"] + outer["width"]
+        and inner["y"] + inner["height"] <= outer["y"] + outer["height"]
+    )
+
+
+def _shrink(rect: dict[str, int], margin: int) -> dict[str, int] | None:
+    width = rect["width"] - 2 * margin
+    height = rect["height"] - 2 * margin
+    if width <= 0 or height <= 0:
+        return None
+    return {
+        "x": rect["x"] + margin,
+        "y": rect["y"] + margin,
+        "width": width,
+        "height": height,
+    }
+
+
+def validate(document: dict[str, Any], root: Path, allow_shared_source: bool = False) -> dict[str, Any]:
+    base = AC.validate_frame_geometry(document, root)
+    errors = list(base.get("errors", []))
+    warnings = list(base.get("warnings", []))
+    frames = document.get("frames") if isinstance(document.get("frames"), list) else []
+    canvas = document.get("canvas") if isinstance(document.get("canvas"), dict) else {}
+    canvas_width = int(canvas.get("width", 0) or 0)
+    canvas_height = int(canvas.get("height", 0) or 0)
+
+    measurements_by_id = {
+        str(item.get("frame_id")): item
+        for item in base.get("metrics", {}).get("measurements", [])
+        if isinstance(item, dict)
+    }
+
+    seen_images: dict[str, int] = {}
+    for index, frame in enumerate(frames):
+        if not isinstance(frame, dict):
+            continue
+        prefix = f"frames[{index}]"
+        image_value = str(frame.get("image", ""))
+        if image_value:
+            if image_value in seen_images and not allow_shared_source:
+                errors.append(
+                    _error(
+                        "shared_source_image",
+                        f"generated source frame reuses image {image_value!r}; use one isolated image per source frame",
+                        f"{prefix}.image",
+                    )
+                )
+            seen_images[image_value] = index
+
+        rect = frame.get("rect") if isinstance(frame.get("rect"), dict) else None
+        if rect and canvas_width > 0 and canvas_height > 0 and not allow_shared_source:
+            expected = {"x": 0, "y": 0, "width": canvas_width, "height": canvas_height}
+            try:
+                actual = _normalise_rect(rect)
+            except (KeyError, TypeError, ValueError):
+                actual = {}
+            if actual != expected:
+                errors.append(
+                    _error(
+                        "non_isolated_source",
+                        f"generated source frame rect must own the full {canvas_width}x{canvas_height} canvas before atlas packing",
+                        f"{prefix}.rect",
+                    )
+                )
+
+        frame_id = str(frame.get("frame_id", ""))
+        measurement = measurements_by_id.get(frame_id)
+        safe_rect_value = frame.get("safe_rect") if isinstance(frame.get("safe_rect"), dict) else None
+        if measurement and safe_rect_value:
+            try:
+                safe_rect = _normalise_rect(safe_rect_value)
+                bbox = _normalise_rect(measurement["alpha_bbox"])
+                margin = int(frame.get("bleed_margin_px", 0) or 0)
+                guarded = _shrink(safe_rect, margin)
+            except (KeyError, TypeError, ValueError):
+                guarded = None
+                bbox = None
+            if guarded is None:
+                errors.append(
+                    _error(
+                        "invalid_guard_band",
+                        "safe_rect is too small for the declared bleed_margin_px",
+                        f"{prefix}.bleed_margin_px",
+                    )
+                )
+            elif bbox is not None and not _contains(guarded, bbox):
+                errors.append(
+                    _error(
+                        "guard_band_violation",
+                        f"measured alpha bbox {bbox} leaves less than {frame.get('bleed_margin_px', 0)}px inside safe_rect {safe_rect}",
+                        f"{prefix}.safe_rect",
+                    )
+                )
+
+    remaining_warnings: list[dict[str, Any]] = []
+    for item in warnings:
+        if isinstance(item, dict) and item.get("code") == "bbox_drift":
+            promoted = dict(item)
+            promoted["severity"] = "error"
+            promoted["message"] = f"{promoted.get('message', 'bbox drift exceeds tolerance')}; generated frame scale drift blocks preflight"
+            errors.append(promoted)
+        else:
+            remaining_warnings.append(item)
+
+    return {
+        "contract": "generated_frame_set_preflight",
+        "ready": not errors,
+        "errors": errors,
+        "warnings": remaining_warnings,
+        "metrics": {
+            **base.get("metrics", {}),
+            "isolated_source_required": not allow_shared_source,
+            "unique_source_images": len(seen_images),
+        },
+        "approval": False,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", required=True, help="frame-geometry contract JSON")
+    parser.add_argument("--root", default=".", help="root used to resolve frame paths")
+    parser.add_argument("--allow-shared-source", action="store_true", help="for imported/shared canvases only; not recommended for generated source frames")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    try:
+        document = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        result = {
+            "contract": "generated_frame_set_preflight",
+            "ready": False,
+            "errors": [_error("invalid_input", str(exc), args.input)],
+            "warnings": [],
+            "metrics": {},
+            "approval": False,
+        }
+    else:
+        if not isinstance(document, dict):
+            result = {
+                "contract": "generated_frame_set_preflight",
+                "ready": False,
+                "errors": [_error("invalid_input", "contract root must be an object", args.input)],
+                "warnings": [],
+                "metrics": {},
+                "approval": False,
+            }
+        else:
+            result = validate(document, Path(args.root).resolve(), args.allow_shared_source)
+
+    if args.as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"generated frame-set preflight: {'PASS' if result['ready'] else 'FAIL'}")
+        for item in result.get("errors", []):
+            print(f"ERROR {item.get('code')}: {item.get('message')}")
+        for item in result.get("warnings", []):
+            print(f"WARN  {item.get('code')}: {item.get('message')}")
+    return 0 if result["ready"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tests/scripts/test_asset_consistency.py

@@ -18,19 +18,21 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[2]
 FIXTURE_ROOT = ROOT / "examples/agent-consumer/asset-consistency"
 ANALYZER_PATH = ROOT / "scripts/asset-consistency.py"
+PREFLIGHT_PATH = ROOT / "scripts/frame-set-preflight.py"
 
 
-def load_analyzer():
-    spec = importlib.util.spec_from_file_location("asset_consistency", ANALYZER_PATH)
+def load_module(path: Path, name: str):
+    spec = importlib.util.spec_from_file_location(name, path)
     if spec is None or spec.loader is None:
-        raise RuntimeError("cannot load asset consistency analyzer")
+        raise RuntimeError(f"cannot load {path.name}")
     module = importlib.util.module_from_spec(spec)
     sys.modules[spec.name] = module
     spec.loader.exec_module(module)
     return module
 
 
-AC = load_analyzer()
+AC = load_module(ANALYZER_PATH, "asset_consistency")
+PREFLIGHT = load_module(PREFLIGHT_PATH, "frame_set_preflight")
 
 
 def read_json(name: str) -> dict:
@@ -112,6 +114,65 @@ def test_frame_contamination_and_pivot_drift() -> None:
     check(not result["ready"] and any(item["code"] == "pivot_drift" for item in result["errors"]), "pivot drift must block")
 
 
+def test_generated_frame_set_preflight() -> None:
+    geometry = read_json("hero-walk-frame-geometry.json")
+    result = PREFLIGHT.validate(geometry, FIXTURE_ROOT)
+    check(result["ready"], f"isolated generated frame fixture must pass preflight: {result}")
+    check(result.get("approval") is False, "preflight must never emit approval")
+
+    shared = read_json("hero-walk-frame-geometry.json")
+    shared["frames"][1]["image"] = shared["frames"][0]["image"]
+    shared["frames"][1]["sha256"] = shared["frames"][0]["sha256"]
+    result = PREFLIGHT.validate(shared, FIXTURE_ROOT)
+    check(
+        not result["ready"] and any(item["code"] == "shared_source_image" for item in result["errors"]),
+        "generated multi-frame source must reject a shared pose-sheet image",
+    )
+
+    guard = read_json("hero-walk-frame-geometry.json")
+    guard["frames"][0]["safe_rect"] = {"x": 2, "y": 1, "width": 4, "height": 5}
+    guard["frames"][0]["bleed_margin_px"] = 1
+    result = PREFLIGHT.validate(guard, FIXTURE_ROOT)
+    check(
+        not result["ready"] and any(item["code"] == "guard_band_violation" for item in result["errors"]),
+        "generated frame alpha must preserve the declared transparent guard band",
+    )
+
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        geometry = read_json("hero-walk-frame-geometry.json")
+        geometry["frames"] = [copy.deepcopy(geometry["frames"][0]), copy.deepcopy(geometry["frames"][1])]
+        geometry["invariants"]["bbox_drift_tolerance_px"] = 0
+        for frame in geometry["frames"]:
+            frame["rect"] = {"x": 0, "y": 0, "width": 8, "height": 8}
+            frame["safe_rect"] = {"x": 0, "y": 0, "width": 8, "height": 8}
+            frame["bleed_margin_px"] = 0
+
+        first_pixels = solid(8, 8, (0, 0, 0, 0))
+        for y in range(1, 6):
+            for x in range(2, 6):
+                first_pixels[y * 8 + x] = (120, 160, 220, 255)
+        second_pixels = solid(8, 8, (0, 0, 0, 0))
+        for y in range(1, 6):
+            for x in range(1, 7):
+                second_pixels[y * 8 + x] = (120, 160, 220, 255)
+        write_rgba_png(root / "frame-00.png", 8, 8, first_pixels)
+        write_rgba_png(root / "frame-01.png", 8, 8, second_pixels)
+
+        geometry["frames"][0]["image"] = "frame-00.png"
+        geometry["frames"][0]["alpha_bbox"] = {"x": 2, "y": 1, "width": 4, "height": 5}
+        geometry["frames"][0]["sha256"] = hashlib.sha256((root / "frame-00.png").read_bytes()).hexdigest()
+        geometry["frames"][1]["image"] = "frame-01.png"
+        geometry["frames"][1]["alpha_bbox"] = {"x": 1, "y": 1, "width": 6, "height": 5}
+        geometry["frames"][1]["sha256"] = hashlib.sha256((root / "frame-01.png").read_bytes()).hexdigest()
+
+        result = PREFLIGHT.validate(geometry, root)
+        check(
+            not result["ready"] and any(item["code"] == "bbox_drift" for item in result["errors"]),
+            "generated frame apparent-size drift beyond tolerance must block instead of warning",
+        )
+
+
 def test_atlas_overlap_and_contamination() -> None:
     atlas = read_json("hero-atlas-contract.json")
     atlas["regions"][1]["rect"]["x"] = 4
@@ -179,11 +240,23 @@ def test_missing_file_and_cli_surface() -> None:
     data = json.loads(cli.stdout)
     check(cli.returncode == 0 and data.get("ready") is True and data.get("contract") == "layered_map", "CLI must expose the consistency validator")
 
+    preflight_cli = subprocess.run([
+        sys.executable, str(PREFLIGHT_PATH),
+        "--input", str(FIXTURE_ROOT / "hero-walk-frame-geometry.json"),
+        "--root", str(FIXTURE_ROOT), "--json",
+    ], cwd=ROOT, capture_output=True, text=True)
+    preflight_data = json.loads(preflight_cli.stdout)
+    check(
+        preflight_cli.returncode == 0 and preflight_data.get("ready") is True and preflight_data.get("approval") is False,
+        "generated frame-set preflight CLI must pass isolated fixture without granting approval",
+    )
+
 
 def main() -> int:
     test_pass_fixtures()
     test_identity_and_action_fail_closed()
     test_frame_contamination_and_pivot_drift()
+    test_generated_frame_set_preflight()
     test_atlas_overlap_and_contamination()
     test_layered_map_order_seam_and_bounds()
     test_missing_file_and_cli_surface()