motionloom 2.3.0 → 2.4.0

package/src/output/runtime-pilot-framer/motion-spec.json

@@ -0,0 +1,25 @@
+{
+  "version": "1.0",
+  "scene": "runtime-pilot-framer",
+  "task_id": "runtime-pilot-001",
+  "category": "runtime-pilot",
+  "framework": "framer-motion",
+  "duration_s": 1.2,
+  "fps": 60,
+  "total_frames": 72,
+  "loop": true,
+  "easing": "piecewise scrubbed transform",
+  "camera": null,
+  "theme": {
+    "primary": "#2563EB",
+    "accent": "#F59E0B"
+  },
+  "performance": {
+    "max_file_kb": 300,
+    "max_layers": 8
+  },
+  "source_binding": "hash-bound code-authored scene.jsx; no generated visual asset is asserted",
+  "accessibility": {
+    "reduced_motion": "manual review uses discrete checkpoints"
+  }
+}

package/src/output/runtime-pilot-framer/runtime-evidence.json

@@ -0,0 +1,96 @@
+{
+  "schema_version": "1.1",
+  "run_id": "1786808870894-145958",
+  "generated_at": "2026-08-15T15:47:52.510Z",
+  "mode": "runtime",
+  "harness": "tests/runtime-harness",
+  "status": "pass",
+  "frameworks": [
+    {
+      "run_id": "1786808870894-145958",
+      "framework": "framer-motion",
+      "url": "http://127.0.0.1:4179/tests/runtime-harness/index.html?framework=framer-motion",
+      "status": "pass",
+      "ready": true,
+      "runtime": "framer-motion@13.1.0",
+      "frames": [
+        {
+          "percent": 0,
+          "file": "artifacts/runtime-adapters/framer-motion/frame-00.png",
+          "state": {
+            "progress": 0,
+            "transform": "matrix(0.82, 0, 0, 0.82, 0, 0)",
+            "opacity": "0.28",
+            "contract": {
+              "framework": "framer-motion",
+              "checkpoints": [
+                0,
+                50,
+                100
+              ],
+              "durationSeconds": 1.2,
+              "loop": true,
+              "sourceAuthority": "code_authored"
+            }
+          }
+        },
+        {
+          "percent": 50,
+          "file": "artifacts/runtime-adapters/framer-motion/frame-50.png",
+          "state": {
+            "progress": 0.5,
+            "transform": "matrix(1.02851, -0.256437, 0.256437, 1.02851, 176, -48)",
+            "opacity": "1",
+            "contract": {
+              "framework": "framer-motion",
+              "checkpoints": [
+                0,
+                50,
+                100
+              ],
+              "durationSeconds": 1.2,
+              "loop": true,
+              "sourceAuthority": "code_authored"
+            }
+          }
+        },
+        {
+          "percent": 100,
+          "file": "artifacts/runtime-adapters/framer-motion/frame-100.png",
+          "state": {
+            "progress": 1,
+            "transform": "matrix(0.882948, 0.469472, -0.469472, 0.882948, 240, -36)",
+            "opacity": "1",
+            "contract": {
+              "framework": "framer-motion",
+              "checkpoints": [
+                0,
+                50,
+                100
+              ],
+              "durationSeconds": 1.2,
+              "loop": true,
+              "sourceAuthority": "code_authored"
+            }
+          }
+        }
+      ],
+      "console_errors": [],
+      "telemetry": {
+        "file": "framer-motion/runtime-telemetry.json",
+        "sha256": "1c11a49eac8fb6c87977ccb84cccc59162fa015c73424a07690785bac094e773",
+        "metrics": {
+          "sample_count": 3,
+          "raf_interval_count": 9,
+          "max_raf_interval_ms": 16.799999999999955,
+          "p95_raf_interval_ms": 16.799999999999955
+        }
+      }
+    }
+  ],
+  "scene": "runtime-pilot-framer",
+  "task_id": "runtime-pilot-001",
+  "source_sha256": "f4c0e56de842cae6b234566b556e4f07154f8109dde382a474218a9de8b45a8b",
+  "manifest_sha256": "2b53bf3b6fc8dfe16a271ecd52ec51c2acb5b612c0b77d9fd4e485696989011d",
+  "motion_ir_sha256": "1d339ca2ec9c510e54e53c37ef32c2ddf1485dbaec97c5e9aa178a8f6c9c3287"
+}

package/src/output/runtime-pilot-framer/runtime-telemetry.json

@@ -0,0 +1,100 @@
+{
+  "schema_version": "1.0",
+  "run_id": "1786808553918-145614",
+  "generated_at": "2026-08-15T15:42:35.907Z",
+  "mode": "runtime-telemetry",
+  "task_id": "runtime-pilot-001",
+  "scene": "runtime-pilot-framer",
+  "framework": "framer-motion",
+  "runtime": "framer-motion@13.1.0",
+  "samples": [
+    {
+      "sequence": 0,
+      "percent": 0,
+      "captured_at_ms": 760.7000000476837,
+      "raf_intervals_ms": [
+        16.700000000000045,
+        16.600000000000023,
+        16.699999999999932
+      ],
+      "state_sha256": "0769bb6867251ff8d951b01e7d817ab4644d1f7d4a38b0e91ad54ec5b0f81f6b",
+      "state": {
+        "progress": 0,
+        "transform": "matrix(0.82, 0, 0, 0.82, 0, 0)",
+        "opacity": "0.28",
+        "contract": {
+          "framework": "framer-motion",
+          "checkpoints": [
+            0,
+            50,
+            100
+          ],
+          "durationSeconds": 1.2,
+          "loop": true,
+          "sourceAuthority": "code_authored"
+        }
+      }
+    },
+    {
+      "sequence": 1,
+      "percent": 50,
+      "captured_at_ms": 844.1000000238419,
+      "raf_intervals_ms": [
+        16.600000000000023,
+        16.799999999999955,
+        16.600000000000023
+      ],
+      "state_sha256": "015ad2af517be79a3cf102b48b5f61282acd1843c7b5efe20472c2752d79c890",
+      "state": {
+        "progress": 0.5,
+        "transform": "matrix(1.02851, -0.256437, 0.256437, 1.02851, 176, -48)",
+        "opacity": "1",
+        "contract": {
+          "framework": "framer-motion",
+          "checkpoints": [
+            0,
+            50,
+            100
+          ],
+          "durationSeconds": 1.2,
+          "loop": true,
+          "sourceAuthority": "code_authored"
+        }
+      }
+    },
+    {
+      "sequence": 2,
+      "percent": 100,
+      "captured_at_ms": 927.7000000476837,
+      "raf_intervals_ms": [
+        16.700000000000045,
+        16.699999999999932,
+        16.700000000000045
+      ],
+      "state_sha256": "275a832573d3c660f6d820256f95412e253f0a29c02e8f535dfdec2c47e56de2",
+      "state": {
+        "progress": 1,
+        "transform": "matrix(0.882948, 0.469472, -0.469472, 0.882948, 240, -36)",
+        "opacity": "1",
+        "contract": {
+          "framework": "framer-motion",
+          "checkpoints": [
+            0,
+            50,
+            100
+          ],
+          "durationSeconds": 1.2,
+          "loop": true,
+          "sourceAuthority": "code_authored"
+        }
+      }
+    }
+  ],
+  "metrics": {
+    "sample_count": 3,
+    "raf_interval_count": 9,
+    "max_raf_interval_ms": 16.799999999999955,
+    "p95_raf_interval_ms": 16.799999999999955
+  },
+  "status": "pass"
+}

package/src/output/runtime-pilot-framer/scene.jsx

@@ -0,0 +1,52 @@
+import React, { useEffect, useRef } from "react";
+import { motion, motionValue, useTransform } from "framer-motion";
+
+/**
+ * MotionLoom runtime-first pilot source.
+ * Design: code-authored, deterministic scrub only; review remains human-gated.
+ */
+export const RUNTIME_PILOT_CONTRACT = Object.freeze({
+  framework: "framer-motion",
+  checkpoints: [0, 50, 100],
+  durationSeconds: 1.2,
+  loop: true,
+  sourceAuthority: "code_authored",
+});
+
+export function FramerRuntimePilot({ expose }) {
+  const progress = useRef(motionValue(0)).current;
+  const x = useTransform(progress, [0, 0.5, 1], [0, 176, 240]);
+  const y = useTransform(progress, [0, 0.5, 1], [0, -48, -36]);
+  const rotate = useTransform(progress, [0, 0.5, 1], [0, -14, 28]);
+  const opacity = useTransform(progress, [0, 0.15, 1], [0.28, 1, 1]);
+  const scale = useTransform(progress, [0, 0.5, 1], [0.82, 1.06, 1]);
+
+  useEffect(() => {
+    const box = document.querySelector(".runtime-pilot-box");
+    const adapter = {
+      framework: RUNTIME_PILOT_CONTRACT.framework,
+      runtime: "framer-motion@13.1.0",
+      status: "ready",
+      ready: true,
+      setProgress(value) {
+        progress.set(Math.max(0, Math.min(1, Number(value))));
+      },
+      getState() {
+        return {
+          progress: progress.get(),
+          transform: box ? getComputedStyle(box).transform : "",
+          opacity: box ? getComputedStyle(box).opacity : "",
+          contract: RUNTIME_PILOT_CONTRACT,
+        };
+      },
+    };
+    expose(adapter);
+    adapter.setProgress(0);
+  }, [expose, progress]);
+
+  return (
+    <div className="stage" aria-label="MotionLoom Framer Motion runtime pilot">
+      <motion.div className="motion-box runtime-pilot-box" style={{ x, y, rotate, opacity, scale }} />
+    </div>
+  );
+}

package/src/output/runtime-pilot-framer/snapshot/.render-meta.json

@@ -0,0 +1,9 @@
+{
+  "mode": "runtime",
+  "scene": "runtime-pilot-framer",
+  "framework": "framer-motion",
+  "run_id": "1786808553918-145614",
+  "source_sha256": "f4c0e56de842cae6b234566b556e4f07154f8109dde382a474218a9de8b45a8b",
+  "runtime_evidence": "../runtime-evidence.json",
+  "checkpoints": [0, 50, 100]
+}

package/tests/scripts/run_tests.py

@@ -359,6 +359,42 @@ def test_deep_audit_contracts():
         ], capture_output=True, text=True)
         check("review hook rejects expired candidate", expired.returncode != 0 and "expired" in expired.stdout)
 
+
+def test_task_bundle_resolver_contract():
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        opaque_task = root / "artifacts" / "opaque-task-id"
+        shutil.copytree(ROOT / "artifacts/runtime-pilot-001", opaque_task)
+        resolver = ROOT / "scripts/resolve-task-bundle.py"
+        resolved = subprocess.run([
+            sys.executable, str(resolver), "--root", str(root), "--scene", "runtime-pilot-framer",
+        ], capture_output=True, text=True)
+        check(
+            "task bundle resolver binds scene to opaque task directory",
+            resolved.returncode == 0 and resolved.stdout.strip() == "artifacts/opaque-task-id",
+            resolved.stdout.strip() or resolved.stderr.strip(),
+        )
+
+        duplicate = root / "artifacts" / "second-task-id"
+        shutil.copytree(opaque_task, duplicate)
+        ambiguous = subprocess.run([
+            sys.executable, str(resolver), "--root", str(root), "--scene", "runtime-pilot-framer",
+        ], capture_output=True, text=True)
+        check(
+            "task bundle resolver rejects ambiguous scene bindings",
+            ambiguous.returncode != 0 and "ambiguous task bundles" in ambiguous.stderr,
+            ambiguous.stdout.strip() or ambiguous.stderr.strip(),
+        )
+
+        unsafe = subprocess.run([
+            sys.executable, str(resolver), "--root", str(root), "--scene", "../runtime-pilot-framer",
+        ], capture_output=True, text=True)
+        check(
+            "task bundle resolver rejects unsafe scene identifiers",
+            unsafe.returncode != 0 and "unsafe scene" in unsafe.stderr,
+            unsafe.stdout.strip() or unsafe.stderr.strip(),
+        )
+
     unsafe_runtime = subprocess.run(
         ["node", str(ROOT / "scripts/runtime-adapters.mjs")],
         env={**os.environ, "RUNTIME_FRAMEWORKS": "../../escape"},
@@ -945,6 +981,76 @@ def test_quality_workflow_rebuilds_replay_after_generated_artifacts():
         asset_provenance_tests.returncode == 0 and "asset provenance contract tests: PASS" in asset_provenance_tests.stdout,
         asset_provenance_tests.stdout.strip() or asset_provenance_tests.stderr.strip(),
     )
+    asset_consistency_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_asset_consistency.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Asset consistency preserves deterministic geometry, atlas and layered-map boundaries",
+        asset_consistency_tests.returncode == 0 and "asset consistency contract tests: PASS" in asset_consistency_tests.stdout,
+        asset_consistency_tests.stdout.strip() or asset_consistency_tests.stderr.strip(),
+    )
+    artifact_intake_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_artifact_intake.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Artifact intake preserves provider-neutral controls, hash binding and approval boundaries",
+        artifact_intake_tests.returncode == 0 and "artifact intake contract tests: PASS" in artifact_intake_tests.stdout,
+        artifact_intake_tests.stdout.strip() or artifact_intake_tests.stderr.strip(),
+    )
+    runtime_candidate_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_runtime_candidate.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Runtime candidate bridge binds intake exports, consistency and human review boundaries",
+        runtime_candidate_tests.returncode == 0 and "runtime candidate contract tests: PASS" in runtime_candidate_tests.stdout,
+        runtime_candidate_tests.stdout.strip() or runtime_candidate_tests.stderr.strip(),
+    )
+    rig_compatibility_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_rig_compatibility.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Rig compatibility preserves skeleton, socket, event, runtime evidence and review boundaries",
+        rig_compatibility_tests.returncode == 0 and "rig compatibility contract tests: PASS" in rig_compatibility_tests.stdout,
+        rig_compatibility_tests.stdout.strip() or rig_compatibility_tests.stderr.strip(),
+    )
+    rive_package_gate_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_rive_package_gate.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Rive package gate requires authentic package bytes, runtime proof and human review",
+        rive_package_gate_tests.returncode == 0 and "rive package gate contract tests: PASS" in rive_package_gate_tests.stdout,
+        rive_package_gate_tests.stdout.strip() or rive_package_gate_tests.stderr.strip(),
+    )
+    ai_pilot_builder_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_ai_pilot_builder.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "AI pilot builder requires real alpha, hash-binds artifacts and preserves review-first status",
+        ai_pilot_builder_tests.returncode == 0 and "AI pilot builder tests: PASS" in ai_pilot_builder_tests.stdout,
+        ai_pilot_builder_tests.stdout.strip() or ai_pilot_builder_tests.stderr.strip(),
+    )
+    alpha_isolation_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_alpha_isolation.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Alpha isolation only removes reviewed edge-connected background and rejects residual contamination",
+        alpha_isolation_tests.returncode == 0 and "alpha isolation tests: PASS" in alpha_isolation_tests.stdout,
+        alpha_isolation_tests.stdout.strip() or alpha_isolation_tests.stderr.strip(),
+    )
 
 
 if __name__ == "__main__":
@@ -961,6 +1067,7 @@ if __name__ == "__main__":
     test_placeholder_is_not_runtime_evidence()
     test_runtime_evidence_binding()
     test_deep_audit_contracts()
+    test_task_bundle_resolver_contract()
     test_runtime_telemetry_verifier_contract()
     test_approved_browser_review_e2e_contract()
     test_intelligence_core_contracts()

package/tests/scripts/test_ai_pilot_builder.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+BUILDER = ROOT / "scripts" / "build-ai-pilot.py"
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def write_png(path: Path, alpha: bool, offset: int = 0, contamination: bool = False) -> None:
+    """Write one compact, non-interlaced 4x4 PNG without third-party libraries."""
+    width = height = 4
+    channels = 4 if alpha else 3
+    rows = bytearray()
+    for y in range(height):
+        rows.append(0)
+        for x in range(width):
+            visible = (x == 1 + offset and y in {1, 2}) or (contamination and x == 3 and y == 1)
+            rows.extend((244, 124, 21))
+            if alpha:
+                rows.append(255 if visible else 0)
+    def chunk(kind: bytes, data: bytes) -> bytes:
+        return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
+    color_type = 6 if alpha else 2
+    path.write_bytes(b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, color_type, 0, 0, 0)) + chunk(b"IDAT", zlib.compress(bytes(rows))) + chunk(b"IEND", b""))
+
+
+def build(root: Path, sources: dict[str, Path], output: str, provider: str = "internal-imagegen") -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable, str(BUILDER),
+            "--idle", str(sources["idle"]),
+            "--contact-right", str(sources["contact-right"]),
+            "--passing", str(sources["passing"]),
+            "--contact-left", str(sources["contact-left"]),
+            "--root", str(root),
+            "--output", output,
+            "--generated-at", "2026-08-15T00:00:00Z",
+            "--provider", provider,
+            "--overwrite",
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+
+def main() -> int:
+    output = ".motionloom/pilots/test-ai-pilot-builder"
+    workspace = ROOT / output
+    shutil.rmtree(workspace, ignore_errors=True)
+    with tempfile.TemporaryDirectory() as td:
+        source_dir = Path(td)
+        sources: dict[str, Path] = {}
+        for index, frame_id in enumerate(("idle", "contact-right", "passing", "contact-left")):
+            source = source_dir / f"{frame_id}.png"
+            write_png(source, alpha=True, offset=index % 2)
+            sources[frame_id] = source
+        result = build(ROOT, sources, output)
+        check(result.returncode == 0, result.stderr or result.stdout)
+        provenance = json.loads((workspace / "provenance.json").read_text())
+        candidate = json.loads((workspace / "candidate.json").read_text())
+        evidence = json.loads((workspace / "devlab-pilot-evidence.json").read_text())
+        check(provenance["authority"] == "ai_generated" and provenance["readiness"] == "runtime_ready", "builder must preserve AI authority/readiness")
+        check("human_approval" not in provenance and candidate["runtime"]["review_required"] is True, "builder must not self-approve a candidate")
+        check(evidence["state"] == "review_required" and evidence["production_approved"] is False, "Dev Lab evidence must retain review boundary")
+        intake = subprocess.run(
+            [sys.executable, str(ROOT / "scripts/artifact-intake.py"), "intake", "--root", str(ROOT), "--registry", str(ROOT / "artifact-adapter-registry.json"), "--controls", str(workspace / "controls.json"), "--receipt", str(workspace / "receipt.json"), "--export-manifest", str(workspace / "export.json"), "--json"],
+            capture_output=True,
+            text=True,
+        )
+        intake_data = json.loads(intake.stdout)
+        check(intake.returncode == 0 and intake_data["status"] == "review_required", intake.stderr or intake.stdout)
+        runtime = subprocess.run(
+            [sys.executable, str(ROOT / "scripts/runtime-candidate.py"), "validate", "--root", str(ROOT), "--input", str(workspace / "candidate.json"), "--json"],
+            capture_output=True,
+            text=True,
+        )
+        runtime_data = json.loads(runtime.stdout)
+        check(runtime.returncode == 0 and runtime_data["status"] == "review_required" and runtime_data["runtime_verified"] is False, runtime.stderr or runtime.stdout)
+
+        chatgpt_output = ".motionloom/pilots/test-ai-pilot-chatgpt"
+        chatgpt = build(ROOT, sources, chatgpt_output, provider="chatgpt")
+        check(chatgpt.returncode == 0, chatgpt.stderr or chatgpt.stdout)
+        chatgpt_workspace = ROOT / chatgpt_output
+        chatgpt_provenance = json.loads((chatgpt_workspace / "provenance.json").read_text())
+        chatgpt_receipt = json.loads((chatgpt_workspace / "receipt.json").read_text())
+        check(chatgpt_provenance["generator"]["source"] == "openai-chatgpt", "ChatGPT import must not be relabelled internal-imagegen")
+        check(chatgpt_receipt["provider"]["adapter_id"] == "openai.chatgpt" and chatgpt_receipt["provider"]["invocation_mode"] == "manual", "ChatGPT receipt must preserve user-mediated adapter truth")
+
+        opaque = source_dir / "opaque.png"
+        write_png(opaque, alpha=False)
+        opaque_output = ".motionloom/pilots/test-ai-pilot-opaque"
+        rejected = build(ROOT, {key: opaque for key in sources}, opaque_output)
+        check(rejected.returncode != 0 and "has no alpha channel" in (rejected.stderr + rejected.stdout), "RGB checkered source must be rejected as non-alpha")
+        opaque_handoff = json.loads((ROOT / opaque_output / "partial-handoff.json").read_text())
+        check(opaque_handoff["state"] == "partial" and opaque_handoff["production_approved"] is False, "early RGB rejection must emit a non-approving partial handoff")
+        check(len(opaque_handoff["rejected_source_attempts"][0]["frames"]) == 4, "partial handoff must bind every supplied source hash")
+
+        contaminated = source_dir / "contaminated.png"
+        write_png(contaminated, alpha=True, contamination=True)
+        contaminated_output = ".motionloom/pilots/test-ai-pilot-contaminated"
+        rejected = build(ROOT, {key: contaminated for key in sources}, contaminated_output, provider="chatgpt")
+        check(rejected.returncode != 0 and "clean padding" in (rejected.stderr + rejected.stdout), "detached canvas-edge contamination must be rejected")
+        contaminated_handoff = json.loads((ROOT / contaminated_output / "partial-handoff.json").read_text())
+        attempt = contaminated_handoff["rejected_source_attempts"][0]
+        check(attempt["provider"] == "openai-chatgpt" and attempt["state"] == "rejected_pre_ingest", "partial handoff must preserve ChatGPT provenance")
+    shutil.rmtree(workspace, ignore_errors=True)
+    shutil.rmtree(ROOT / ".motionloom/pilots/test-ai-pilot-chatgpt", ignore_errors=True)
+    shutil.rmtree(ROOT / ".motionloom/pilots/test-ai-pilot-opaque", ignore_errors=True)
+    shutil.rmtree(ROOT / ".motionloom/pilots/test-ai-pilot-contaminated", ignore_errors=True)
+    print("AI pilot builder tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tests/scripts/test_alpha_isolation.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+ISOLATOR = ROOT / "scripts" / "isolate-alpha-background.py"
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def write_png(path: Path, contamination: bool = False) -> None:
+    width = height = 8
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        for x in range(width):
+            if 2 <= x <= 5 and 2 <= y <= 5:
+                color = (244, 124, 21, 255)
+            elif contamination and x == width - 1 and y == 3:
+                color = (180, 24, 180, 255)
+            else:
+                color = (29, 32, 32, 255)
+            raw.extend(color)
+    def chunk(kind: bytes, content: bytes) -> bytes:
+        return struct.pack(">I", len(content)) + kind + content + struct.pack(">I", zlib.crc32(kind + content) & 0xFFFFFFFF)
+    payload = b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)) + chunk(b"IDAT", zlib.compress(bytes(raw))) + chunk(b"IEND", b"")
+    path.write_bytes(payload)
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        source, output, report = root / "source.png", root / "isolated.png", root / "report.json"
+        write_png(source)
+        result = subprocess.run([sys.executable, str(ISOLATOR), str(source), str(output), "--report", str(report), "--tolerance", "24"], capture_output=True, text=True)
+        check(result.returncode == 0, result.stderr or result.stdout)
+        data = json.loads(report.read_text())
+        check(data["removed_pixels"] == 48 and data["foreground_alpha_pixels"] == 16, "isolator must remove only the edge-connected flat background")
+        check(data["residual_edge_foreground_pixels"] == 0 and data["human_review_required"] is True and data["production_approved"] is False, "isolation must preserve review/approval boundary")
+
+        contaminated = root / "contaminated.png"
+        write_png(contaminated, contamination=True)
+        rejected = subprocess.run([sys.executable, str(ISOLATOR), str(contaminated), str(root / "rejected.png"), "--tolerance", "24"], capture_output=True, text=True)
+        check(rejected.returncode != 0 and "residual background contamination" in (rejected.stderr + rejected.stdout), "edge contamination must fail closed")
+    print("alpha isolation tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())