motionloom 2.3.0 → 2.4.0

package/tests/scripts/test_artifact_intake.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+
+
+ROOT = Path(__file__).resolve().parents[2]
+MODULE_PATH = ROOT / "scripts" / "artifact-intake.py"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("artifact_intake", MODULE_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load artifact intake")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+MODULE = load_module()
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def write(path: Path, document: dict) -> Path:
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def bundle(root: Path) -> tuple[Path, Path, Path, Path]:
+    evidence = root / "evidence.md"
+    evidence.write_text("internal capability evidence\n", encoding="utf-8")
+    frame_a = root / "frame-00.png"
+    frame_b = root / "frame-01.png"
+    frame_a.write_bytes(b"frame-zero")
+    frame_b.write_bytes(b"frame-one")
+    registry = {
+        "schema_version": "0.1", "registry_id": "test-registry", "generated_at": "2026-08-15T00:00:00Z",
+        "selection_policy": {"require_verified": True, "allow_scaffold_only": False},
+        "adapters": [{
+            "adapter_id": "fixture.local", "kind": "fixture", "status": "static_validated", "adapter_version": "0.1",
+            "invocation_mode": "none", "cost_class": "included", "inputs": ["reference"], "outputs": ["frame_sequence"],
+            "compatibility": {"os": ["linux", "macos", "windows"]},
+            "evidence": [{"path": "evidence.md", "sha256": sha(evidence), "kind": "static"}],
+            "limitations": ["fixture only"], "risk_level": "low", "side_effect_level": "read"
+        }]
+    }
+    controls = {
+        "schema_version": "0.1", "control_id": "test-controls", "asset_id": "test-asset", "created_at": "2026-08-15T00:00:00Z",
+        "references": [{"id": "identity", "path": "frame-00.png", "sha256": sha(frame_a), "role": "identity"}],
+        "tracks": [
+            {"id": "identity", "kind": "identity", "binding": "required", "value_hash": "1" * 64},
+            {"id": "pose", "kind": "pose", "binding": "required", "value_hash": "2" * 64, "samples": 2}
+        ],
+        "output_profile": {"kind": "frame_sequence", "fps": 12, "expected_frame_count": 2, "loop": True}
+    }
+    provenance = {
+        "authority": "ai_generated",
+        "files": [{"path": "frame-00.png", "sha256": sha(frame_a)}, {"path": "frame-01.png", "sha256": sha(frame_b)}]
+    }
+    receipt = {
+        "schema_version": "0.1", "receipt_id": "test-receipt", "created_at": "2026-08-15T00:00:00Z",
+        "asset": {"id": "test-asset", "kind": "frame_sequence", "intended_use": "pilot"}, "authority": "ai_generated",
+        "provider": {"adapter_id": "fixture.local", "kind": "fixture", "invocation_mode": "none", "task_id": "task-1", "model": "fixture", "generated_at": "2026-08-15T00:00:00Z", "cost_class": "included"},
+        "control_track_ref": "controls.json", "provenance_ref": "provenance.json",
+        "outputs": [
+            {"path": "frame-00.png", "role": "frame-00", "sha256": sha(frame_a), "bytes": frame_a.stat().st_size},
+            {"path": "frame-01.png", "role": "frame-01", "sha256": sha(frame_b), "bytes": frame_b.stat().st_size}
+        ]
+    }
+    export = {
+        "schema_version": "0.1", "manifest_id": "test-export", "asset_id": "test-asset", "created_at": "2026-08-15T00:00:00Z",
+        "receipt_ref": "receipt.json", "control_track_ref": "controls.json",
+        "outputs": [dict(entry, target="preview") for entry in receipt["outputs"]]
+    }
+    return write(root / "registry.json", registry), write(root / "receipt.json", receipt), write(root / "controls.json", controls), write(root / "export.json", export), write(root / "provenance.json", provenance)
+
+
+def result(root: Path, registry: Path, receipt: Path, controls: Path, export: Path, strict: bool = False) -> dict:
+    return MODULE.evaluate_bundle(SimpleNamespace(root=root, registry=registry, receipt=receipt, controls=controls, export_manifest=export, strict=strict))
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        registry, receipt, controls, export, provenance = bundle(root)
+        valid = result(root, registry, receipt, controls, export)
+        check(valid["ready"] and valid["status"] == "review_required", "static adapter must produce review_required evidence, not approval")
+        check(not valid["production_eligible"] and not valid["production_approved"], "intake must never grant production authority")
+        strict = result(root, registry, receipt, controls, export, strict=True)
+        check(not strict["ready"] and any(item["code"] == "adapter_not_runtime_verified" for item in strict["errors"]), "strict intake must fail a non-verified adapter")
+
+        receipt_doc = json.loads(receipt.read_text())
+        receipt_doc["outputs"][0]["sha256"] = "0" * 64
+        tampered = write(root / "tampered-receipt.json", receipt_doc)
+        bad_hash = result(root, registry, tampered, controls, export)
+        check(not bad_hash["ready"] and any(item["code"] == "sha256_mismatch" for item in bad_hash["errors"]), "output hash tampering must fail closed")
+
+        unknown_doc = copy.deepcopy(json.loads(receipt.read_text()))
+        unknown_doc["provider"]["adapter_id"] = "missing.adapter"
+        unknown = write(root / "unknown-receipt.json", unknown_doc)
+        unknown_result = result(root, registry, unknown, controls, export)
+        check(not unknown_result["ready"] and any(item["code"] == "unknown_adapter" for item in unknown_result["errors"]), "unknown adapter must fail closed")
+
+        approval_doc = copy.deepcopy(json.loads(receipt.read_text()))
+        approval_doc["production_approved"] = True
+        approval = write(root / "approval-receipt.json", approval_doc)
+        approval_result = result(root, registry, approval, controls, export)
+        check(not approval_result["ready"] and any(item["code"] == "approval_forbidden" for item in approval_result["errors"]), "receipt cannot self-assert approval")
+
+        controls_doc = json.loads(controls.read_text())
+        controls_doc["tracks"] = [controls_doc["tracks"][0]]
+        no_motion = write(root / "no-motion-controls.json", controls_doc)
+        no_motion_result = result(root, registry, receipt, no_motion, export)
+        check(not no_motion_result["ready"] and any(item["code"] == "missing_motion_control" for item in no_motion_result["errors"]), "animated output requires motion or pose controls")
+
+        export_doc = json.loads(export.read_text())
+        export_doc["outputs"][1]["sha256"] = "f" * 64
+        bad_export = write(root / "bad-export.json", export_doc)
+        export_result = result(root, registry, receipt, controls, bad_export)
+        check(not export_result["ready"] and any(item["code"] in {"sha256_mismatch", "receipt_output_missing"} for item in export_result["errors"]), "export must bind to receipt bytes")
+
+        cli = subprocess.run([sys.executable, str(MODULE_PATH), "intake", "--root", str(root), "--registry", str(registry), "--receipt", str(receipt), "--controls", str(controls), "--export-manifest", str(export), "--json"], capture_output=True, text=True)
+        cli_result = json.loads(cli.stdout)
+        check(cli.returncode == 0 and cli_result["status"] == "review_required", "CLI must return evidence without provider invocation")
+    print("artifact intake contract tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tests/scripts/test_asset_consistency.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Regression suite for MotionLoom's deterministic asset consistency contracts."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import importlib.util
+import json
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+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"
+
+
+def load_analyzer():
+    spec = importlib.util.spec_from_file_location("asset_consistency", ANALYZER_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load asset consistency analyzer")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+AC = load_analyzer()
+
+
+def read_json(name: str) -> dict:
+    return json.loads((FIXTURE_ROOT / name).read_text(encoding="utf-8"))
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def png_chunk(kind: bytes, payload: bytes) -> bytes:
+    return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", zlib.crc32(kind + payload) & 0xFFFFFFFF)
+
+
+def write_rgba_png(path: Path, width: int, height: int, pixels: list[tuple[int, int, int, int]]) -> None:
+    raw = b"".join(b"\x00" + bytes(sum((list(pixel) for pixel in pixels[y * width : (y + 1) * width]), [])) for y in range(height))
+    header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
+    path.write_bytes(b"\x89PNG\r\n\x1a\n" + png_chunk(b"IHDR", header) + png_chunk(b"IDAT", zlib.compress(raw, 9)) + png_chunk(b"IEND", b""))
+
+
+def solid(width: int, height: int, color: tuple[int, int, int, int]) -> list[tuple[int, int, int, int]]:
+    return [color] * (width * height)
+
+
+def test_pass_fixtures() -> None:
+    identity = AC.validate_identity(read_json("hero-identity.json"))
+    check(identity["ready"], f"identity fixture blocked: {identity}")
+
+    action_set = AC.validate_action_set(read_json("hero-walk-action-set.json"))
+    check(action_set["ready"], f"action-set fixture blocked: {action_set}")
+
+    geometry = AC.validate_frame_geometry(read_json("hero-walk-frame-geometry.json"), FIXTURE_ROOT)
+    check(geometry["ready"], f"frame geometry fixture blocked: {geometry}")
+    check(geometry["metrics"]["frame_count"] == 4, "frame geometry must measure all four frames")
+
+    atlas = AC.validate_atlas(read_json("hero-atlas-contract.json"), FIXTURE_ROOT)
+    check(atlas["ready"], f"atlas fixture blocked: {atlas}")
+    check(atlas["metrics"]["opaque_pixels_outside_regions"] == 0, "atlas fixture must have no outside pixels")
+
+    layered_map = AC.validate_layered_map(read_json("forest-layered-map.json"), FIXTURE_ROOT)
+    check(layered_map["ready"], f"layered-map fixture blocked: {layered_map}")
+    check(layered_map["metrics"]["layer_count"] == 3, "layered-map fixture must measure three layers")
+
+
+def test_identity_and_action_fail_closed() -> None:
+    identity = read_json("hero-identity.json")
+    identity["derivation"]["origin"] = "unknown"
+    result = AC.validate_identity(identity)
+    check(not result["ready"] and any(item["code"] == "unknown_origin" for item in result["errors"]), "unknown identity origin must block")
+
+    action_set = read_json("hero-walk-action-set.json")
+    del action_set["actions"][0]["loop"]
+    result = AC.validate_action_set(action_set)
+    check(not result["ready"] and any(item["code"] == "invalid_loop" for item in result["errors"]), "implicit loop policy must block")
+
+
+def test_frame_contamination_and_pivot_drift() -> None:
+    geometry = read_json("hero-walk-frame-geometry.json")
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        image = [(0, 0, 0, 0)] * 64
+        for y in range(1, 6):
+            for x in range(2, 6):
+                image[y * 8 + x] = (120, 160, 220, 255)
+        image[0] = (255, 0, 0, 255)
+        write_rgba_png(root / "contaminated.png", 8, 8, image)
+        geometry["frames"] = [copy.deepcopy(geometry["frames"][0])]
+        geometry["frames"][0]["image"] = "contaminated.png"
+        geometry["frames"][0]["rect"] = {"x": 1, "y": 1, "width": 6, "height": 6}
+        geometry["frames"][0]["alpha_bbox"] = {"x": 1, "y": 0, "width": 4, "height": 5}
+        geometry["frames"][0]["sha256"] = hashlib.sha256((root / "contaminated.png").read_bytes()).hexdigest()
+        result = AC.validate_frame_geometry(geometry, root)
+        check(not result["ready"] and any(item["code"] == "frame_contamination" for item in result["errors"]), "opaque pixels outside frame rect must block")
+
+    geometry = read_json("hero-walk-frame-geometry.json")
+    geometry["frames"][1]["pivot"]["x"] = 4.5
+    result = AC.validate_frame_geometry(geometry, FIXTURE_ROOT)
+    check(not result["ready"] and any(item["code"] == "pivot_drift" for item in result["errors"]), "pivot drift must block")
+
+
+def test_atlas_overlap_and_contamination() -> None:
+    atlas = read_json("hero-atlas-contract.json")
+    atlas["regions"][1]["rect"]["x"] = 4
+    result = AC.validate_atlas(atlas, FIXTURE_ROOT)
+    check(not result["ready"] and any(item["code"] == "region_overlap" for item in result["errors"]), "overlapping atlas regions must block")
+
+    atlas = read_json("hero-atlas-contract.json")
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        pixels = solid(16, 8, (0, 0, 0, 0))
+        for y in range(1, 7):
+            for x in list(range(1, 7)) + list(range(9, 15)):
+                pixels[y * 16 + x] = (200, 100, 80, 255)
+        pixels[0] = (255, 255, 255, 255)
+        contaminated = root / "atlas.png"
+        write_rgba_png(contaminated, 16, 8, pixels)
+        atlas["image"] = str(contaminated)
+        result = AC.validate_atlas(atlas, root)
+        check(not result["ready"] and any(item["code"] == "atlas_contamination" for item in result["errors"]), "atlas pixels outside regions must block")
+
+
+def test_layered_map_order_seam_and_bounds() -> None:
+    layered_map = read_json("forest-layered-map.json")
+    layered_map["layers"][1]["z_index"] = 0
+    result = AC.validate_layered_map(layered_map, FIXTURE_ROOT)
+    check(not result["ready"] and any(item["code"] == "duplicate_z_index" for item in result["errors"]), "duplicate z-order must block")
+
+    layered_map = read_json("forest-layered-map.json")
+    layered_map["layers"][1]["parallax"]["x"] = 0.1
+    warning = AC.validate_layered_map(layered_map, FIXTURE_ROOT)
+    check(warning["ready"] and any(item["code"] == "parallax_order_drift" for item in warning["warnings"]), "non-monotonic parallax must be visible as a warning")
+    blocked = AC.validate_layered_map(layered_map, FIXTURE_ROOT, strict=True)
+    check(not blocked["ready"] and any(item["code"] == "parallax_order_drift" for item in blocked["errors"]), "strict parallax drift must block")
+
+    layered_map = read_json("forest-layered-map.json")
+    layered_map["camera"]["safe_bounds"] = {"x": 120, "y": 60, "width": 32, "height": 18}
+    result = AC.validate_layered_map(layered_map, FIXTURE_ROOT)
+    check(not result["ready"] and any(item["code"] == "camera_safe_bounds_outside_world" for item in result["errors"]), "camera safe bounds outside world must block")
+
+    with tempfile.TemporaryDirectory() as td:
+        root = Path(td)
+        pixels = solid(4, 4, (0, 0, 0, 255))
+        for y in range(4):
+            pixels[y * 4 + 3] = (255, 255, 255, 255)
+        seam_image = root / "seam.png"
+        write_rgba_png(seam_image, 4, 4, pixels)
+        seam_map = read_json("forest-layered-map.json")
+        seam_map["layers"] = [copy.deepcopy(seam_map["layers"][0])]
+        seam_map["layers"][0]["image"] = str(seam_image)
+        result = AC.validate_layered_map(seam_map, root)
+        check(not result["ready"] and any(item["code"] == "horizontal_seam" for item in result["errors"]), "tileable horizontal seam must block")
+
+
+def test_missing_file_and_cli_surface() -> None:
+    geometry = read_json("hero-walk-frame-geometry.json")
+    geometry["frames"][0]["image"] = "does-not-exist.png"
+    result = AC.validate_frame_geometry(geometry, FIXTURE_ROOT)
+    check(not result["ready"] and any(item["code"] == "image_unreadable" for item in result["errors"]), "missing image must fail closed")
+
+    cli = subprocess.run([
+        "node", str(ROOT / "bin/motionloom.mjs"), "asset-consistency", "validate",
+        "--kind", "layered-map", "--input", str(FIXTURE_ROOT / "forest-layered-map.json"),
+        "--root", str(FIXTURE_ROOT), "--json",
+    ], cwd=ROOT, capture_output=True, text=True)
+    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")
+
+
+def main() -> int:
+    test_pass_fixtures()
+    test_identity_and_action_fail_closed()
+    test_frame_contamination_and_pivot_drift()
+    test_atlas_overlap_and_contamination()
+    test_layered_map_order_seam_and_bounds()
+    test_missing_file_and_cli_surface()
+    print("asset consistency contract tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:
+        print(f"asset consistency contract tests: FAIL — {exc}", file=sys.stderr)
+        raise

package/tests/scripts/test_rig_compatibility.py

@@ -0,0 +1,105 @@
+import copy
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+
+
+ROOT = Path(__file__).resolve().parents[2]
+MODULE_PATH = ROOT / "scripts" / "rig-compatibility.py"
+REGISTRY = ROOT / "rig-adapter-registry.json"
+FIXTURE = ROOT / "examples/agent-consumer/rig-compatibility/hero-walk-fixture-rig.json"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("rig_compatibility", MODULE_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load rig compatibility")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+MODULE = load_module()
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def write(path: Path, document: dict) -> Path:
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def evaluate(path: Path, strict: bool = False) -> dict:
+    return MODULE.validate(SimpleNamespace(root=ROOT, input=path, registry=REGISTRY, strict=strict))
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(dir=ROOT) as td:
+        temp = Path(td)
+        fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
+        valid = evaluate(FIXTURE)
+        check(valid["ready"] and valid["status"] == "review_required", "public fixture must be contract-valid and review-required")
+        check(not valid["runtime_verified"] and not valid["production_eligible"] and not valid["production_approved"], "valid rig evidence must not self-grant runtime or production authority")
+
+        strict = evaluate(FIXTURE, strict=True)
+        check(not strict["ready"] and any(item["code"] == "runtime_evidence_required" for item in strict["errors"]), "strict rig validation must require matching runtime evidence")
+
+        bad_hash = copy.deepcopy(fixture)
+        bad_hash["source"]["sha256"] = "0" * 64
+        bad_hash_path = write(temp / "bad-hash.json", bad_hash)
+        hash_result = evaluate(bad_hash_path)
+        check(not hash_result["ready"] and any(item["code"] == "sha256_mismatch" for item in hash_result["errors"]), "source hash tampering must fail closed")
+
+        duplicate_socket = copy.deepcopy(fixture)
+        duplicate_socket["sockets"].append(dict(duplicate_socket["sockets"][0]))
+        duplicate_socket_path = write(temp / "duplicate-socket.json", duplicate_socket)
+        socket_result = evaluate(duplicate_socket_path)
+        check(not socket_result["ready"] and any(item["code"] == "invalid_socket" for item in socket_result["errors"]), "duplicate sockets must fail")
+
+        missing_event = copy.deepcopy(fixture)
+        missing_event["actions"][0]["events"] = ["footstep.left"]
+        missing_event_path = write(temp / "missing-event.json", missing_event)
+        event_result = evaluate(missing_event_path)
+        check(not event_result["ready"] and any(item["code"] == "required_event_missing" for item in event_result["errors"]), "required rig events must be explicit")
+
+        unknown_adapter = copy.deepcopy(fixture)
+        unknown_adapter["runtime"]["adapter_id"] = "unknown.adapter"
+        unknown_adapter_path = write(temp / "unknown-adapter.json", unknown_adapter)
+        adapter_result = evaluate(unknown_adapter_path)
+        check(not adapter_result["ready"] and any(item["code"] == "unknown_adapter" for item in adapter_result["errors"]), "unknown rig adapter must fail closed")
+
+        no_review = copy.deepcopy(fixture)
+        no_review["runtime"]["review_required"] = False
+        no_review_path = write(temp / "no-review.json", no_review)
+        review_result = evaluate(no_review_path)
+        check(not review_result["ready"] and any(item["code"] == "review_required" for item in review_result["errors"]), "rig contract cannot suppress human review")
+
+        evidence = {
+            "schema_version": "1.1", "run_id": "rig-fixture", "generated_at": "2026-08-15T00:00:00Z",
+            "mode": "runtime", "harness": "fixture", "status": "pass",
+            "frameworks": [{"framework": "sprite", "status": "pass", "ready": True, "frames": [0, 50, 100]}]
+        }
+        evidence_path = write(temp / "runtime-evidence.json", evidence)
+        verified = copy.deepcopy(fixture)
+        verified["runtime"]["runtime_evidence_ref"] = f"{temp.name}/{evidence_path.name}"
+        verified_path = write(temp / "verified.json", verified)
+        verified_result = evaluate(verified_path, strict=True)
+        check(verified_result["ready"] and verified_result["runtime_verified"], "strict rig pass requires a matching ready runtime evidence artifact")
+
+        cli = subprocess.run([sys.executable, str(MODULE_PATH), "validate", "--root", str(ROOT), "--input", str(FIXTURE), "--registry", str(REGISTRY), "--json"], capture_output=True, text=True)
+        cli_result = json.loads(cli.stdout)
+        check(cli.returncode == 0 and cli_result["status"] == "review_required", "rig CLI must return evidence-only review-required state")
+    print("rig compatibility contract tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tests/scripts/test_rive_package_gate.py

@@ -0,0 +1,101 @@
+"""Regression tests for the fail-closed Rive package gate."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.util
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def load_gate():
+    spec = importlib.util.spec_from_file_location("test_rive_package_gate", ROOT / "scripts" / "rive-package-gate.py")
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+GATE = load_gate()
+
+
+def sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+class RivePackageGateTests(unittest.TestCase):
+    def build_bundle(self, directory: Path) -> tuple[Path, Path]:
+        source = directory / "hero.riv"
+        source.write_bytes(b"RIVE\x07\x00demo-real-test-bytes")
+        runtime = directory / "runtime.json"
+        runtime.write_text(json.dumps({"schema_version": "1.0", "run_id": "rive-test", "generated_at": "2026-08-15T00:00:00Z", "mode": "runtime", "harness": "test", "source_sha256": sha(source), "status": "pass", "frameworks": [{"run_id": "rive-test", "framework": "rive", "runtime": "rive-web", "status": "pass", "ready": True, "frames": [0, 50, 100]}]}), encoding="utf-8")
+        provenance = directory / "provenance.json"
+        provenance.write_text(json.dumps({"schema_version": "1.0", "provenance_id": "test-rive", "asset": {"id": "hero-rive", "path": "hero.riv", "type": "character", "framework": "rive"}, "authority": "ai_generated", "readiness": "runtime_ready", "generator": {"model": "internal-imagegen", "task_id": "test", "source": "internal", "generated_at": "2026-08-15T00:00:00Z"}, "files": [{"path": "hero.riv", "role": "runtime-package", "sha256": sha(source), "bytes": source.stat().st_size}], "license": {"spdx": "LicenseRef-AI-Pilot", "source": "internal-imagegen", "attribution": "AI-generated pilot; human review required"}, "provenance_chain": [{"step": "generated", "actor": "agent", "source": "internal-imagegen", "timestamp": "2026-08-15T00:00:00Z"}], "created_at": "2026-08-15T00:00:00Z"}), encoding="utf-8")
+        manifest = directory / "manifest.json"
+        manifest.write_text(json.dumps({"schema_version": "0.1", "package_id": "hero-rive-package", "package_class": "ai_generated_pilot", "asset": {"id": "hero-rive", "path": "hero.riv", "sha256": sha(source), "bytes": source.stat().st_size}, "provenance_ref": "provenance.json", "runtime": {"adapter_id": "motionloom.rive-runtime", "target": "rive", "required_state_machines": ["Locomotion"], "required_inputs": ["speed"], "required_events": ["footstep"], "runtime_evidence_ref": "runtime.json", "runtime_evidence_sha256": sha(runtime), "review_required": True}, "actions": ["idle", "walk"], "review_required": True}), encoding="utf-8")
+        registry = directory / "registry.json"
+        adapter_source = directory / "adapter.mjs"
+        adapter_source.write_text("export const rive = true;\n", encoding="utf-8")
+        registry.write_text(json.dumps({"schema_version": "0.1", "adapters": [{"adapter_id": "motionloom.rive-runtime", "target": "rive", "framework": "rive", "status": "project_integrated", "evidence": [{"path": "adapter.mjs", "sha256": sha(adapter_source)}]}]}), encoding="utf-8")
+        return manifest, registry
+
+    def validate(self, manifest: Path, registry: Path, strict: bool = True):
+        return GATE.validate(argparse.Namespace(input=manifest, root=manifest.parent, registry=registry, strict=strict))
+
+    def test_valid_ai_pilot_is_runtime_test_ready_but_not_approved(self):
+        with tempfile.TemporaryDirectory() as raw:
+            manifest, registry = self.build_bundle(Path(raw))
+            result = self.validate(manifest, registry)
+            self.assertEqual(result["status"], "pass")
+            self.assertTrue(result["runtime_test_ready"])
+            self.assertTrue(result["review_required"])
+            self.assertFalse(result["production_approved"])
+
+    def test_rejects_tampered_riv_bytes(self):
+        with tempfile.TemporaryDirectory() as raw:
+            manifest, registry = self.build_bundle(Path(raw))
+            (Path(raw) / "hero.riv").write_bytes(b"RIVETwitter")
+            result = self.validate(manifest, registry)
+            self.assertEqual(result["status"], "blocked")
+            self.assertTrue(any(item["code"] == "asset_sha256_mismatch" for item in result["issues"]))
+
+    def test_strict_rejects_missing_runtime_proof(self):
+        with tempfile.TemporaryDirectory() as raw:
+            manifest, registry = self.build_bundle(Path(raw))
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+            data["runtime"].pop("runtime_evidence_ref")
+            data["runtime"].pop("runtime_evidence_sha256")
+            manifest.write_text(json.dumps(data), encoding="utf-8")
+            result = self.validate(manifest, registry)
+            self.assertEqual(result["status"], "blocked")
+            self.assertTrue(any(item["code"] == "runtime_evidence_required" for item in result["issues"]))
+
+    def test_rejects_suppressed_review_and_unknown_adapter(self):
+        with tempfile.TemporaryDirectory() as raw:
+            manifest, registry = self.build_bundle(Path(raw))
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+            data["review_required"] = False
+            data["runtime"]["adapter_id"] = "untrusted-rive"
+            manifest.write_text(json.dumps(data), encoding="utf-8")
+            result = self.validate(manifest, registry)
+            self.assertEqual(result["status"], "blocked")
+            codes = {item["code"] for item in result["issues"]}
+            self.assertIn("review_required", codes)
+            self.assertIn("unknown_adapter", codes)
+
+
+if __name__ == "__main__":
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(unittest.defaultTestLoader.loadTestsFromTestCase(RivePackageGateTests))
+    if result.wasSuccessful():
+        print("rive package gate contract tests: PASS")
+        raise SystemExit(0)
+    raise SystemExit(1)

package/tests/scripts/test_runtime_candidate.py

@@ -0,0 +1,95 @@
+import copy
+import importlib.util
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+
+
+ROOT = Path(__file__).resolve().parents[2]
+MODULE_PATH = ROOT / "scripts" / "runtime-candidate.py"
+CANDIDATE_PATH = ROOT / "examples/agent-consumer/runtime-candidate/hero-walk-candidate.json"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("runtime_candidate", MODULE_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load runtime candidate")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+MODULE = load_module()
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def evaluate(path: Path, strict: bool = False) -> dict:
+    return MODULE.validate_candidate(SimpleNamespace(root=ROOT, input=path, strict=strict))
+
+
+def write(path: Path, document: dict) -> Path:
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(dir=ROOT) as td:
+        temp = Path(td)
+        candidate = json.loads(CANDIDATE_PATH.read_text(encoding="utf-8"))
+        public = evaluate(CANDIDATE_PATH)
+        check(public["runtime_test_ready"] and public["status"] == "review_required", "hash-bound public candidate must be runtime-test-ready and review-required")
+        check(not public["runtime_verified"], "candidate without runtime evidence must not self-assert runtime verification")
+        check(not public["production_eligible"] and not public["production_approved"], "candidate bridge must never grant production authority")
+
+        strict = evaluate(CANDIDATE_PATH, strict=True)
+        check(not strict["runtime_test_ready"] and any(item["code"] == "runtime_evidence_required" for item in strict["errors"]), "strict candidate validation must require passing runtime evidence")
+
+        wrong_asset = copy.deepcopy(candidate)
+        wrong_asset["asset_id"] = "character/not-hero"
+        wrong_asset_path = write(temp / "wrong-asset.json", wrong_asset)
+        mismatch = evaluate(wrong_asset_path)
+        check(not mismatch["runtime_test_ready"] and any(item["code"] in {"asset_id_mismatch", "consistency_asset_id_mismatch"} for item in mismatch["errors"]), "candidate asset ID must bind receipt, export and consistency contracts")
+
+        missing_geometry = copy.deepcopy(candidate)
+        del missing_geometry["consistency"]["frame_geometry"]
+        missing_geometry_path = write(temp / "missing-geometry.json", missing_geometry)
+        geometry = evaluate(missing_geometry_path)
+        check(not geometry["runtime_test_ready"] and any(item["code"] == "missing_profile_contract" for item in geometry["errors"]), "frame sequence candidate must require frame geometry evidence")
+
+        no_review = copy.deepcopy(candidate)
+        no_review["runtime"]["review_required"] = False
+        no_review_path = write(temp / "no-review.json", no_review)
+        review = evaluate(no_review_path)
+        check(not review["runtime_test_ready"] and any(item["code"] == "review_required" for item in review["errors"]), "candidate cannot suppress human review")
+
+        evidence = {
+            "schema_version": "1.0", "run_id": "fixture-runtime", "generated_at": "2026-08-15T00:00:00Z",
+            "mode": "runtime", "harness": "fixture", "status": "pass",
+            "frameworks": [{"run_id": "fixture-runtime", "framework": "sprite", "runtime": "fixture", "status": "pass", "ready": True, "frames": [0, 50, 100]}]
+        }
+        evidence_path = temp / "runtime-evidence.json"
+        write(evidence_path, evidence)
+        verified_candidate = copy.deepcopy(candidate)
+        verified_candidate["runtime"]["runtime_evidence_ref"] = f"{temp.name}/runtime-evidence.json"
+        verified_path = write(temp / "verified.json", verified_candidate)
+        verified = evaluate(verified_path, strict=True)
+        check(verified["runtime_test_ready"] and verified["runtime_verified"], "strict candidate may be runtime-verified only with passing evidence")
+
+        cli = subprocess.run([sys.executable, str(MODULE_PATH), "validate", "--root", str(ROOT), "--input", str(CANDIDATE_PATH), "--json"], capture_output=True, text=True)
+        cli_result = json.loads(cli.stdout)
+        check(cli.returncode == 0 and cli_result["status"] == "review_required", "CLI must expose review-required candidate evidence")
+    print("runtime candidate contract tests: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())