motionloom 2.3.0 → 2.4.0

package/scripts/quality-gate.py

@@ -63,6 +63,24 @@ def _load_asset_provenance():
     return module
 
 
+def _load_asset_consistency():
+    path = ROOT / "scripts" / "asset-consistency.py"
+    loader = importlib.util.spec_from_file_location("asset_consistency", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
+def _load_artifact_intake():
+    path = ROOT / "scripts" / "artifact-intake.py"
+    loader = importlib.util.spec_from_file_location("artifact_intake", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
 def _json(path: Path):
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -82,7 +100,7 @@ def _telemetry_bundle_sha256(task_dir: Path) -> str:
     return hashlib.sha256(json.dumps(entries, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
 
 
-def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = False, task_dir: Path | None = None, require_intelligence: bool = False, require_p1: bool = False, require_benchmark: bool = False, require_telemetry: bool = False, require_attestation: bool = False, attestation_path: Path | None = None, trust_policy_path: Path | None = None, require_visual_truth: bool = False, require_asset_provenance: bool = False, asset_provenance_path: Path | None = None) -> list[str]:
+def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = False, task_dir: Path | None = None, require_intelligence: bool = False, require_p1: bool = False, require_benchmark: bool = False, require_telemetry: bool = False, require_attestation: bool = False, attestation_path: Path | None = None, trust_policy_path: Path | None = None, require_visual_truth: bool = False, require_asset_provenance: bool = False, asset_provenance_path: Path | None = None, require_asset_consistency: bool = False, asset_consistency_path: Path | None = None, require_artifact_intake: bool = False) -> list[str]:
     issues = []
     manifest_path = scene_dir / "manifest.json"
     spec_path = scene_dir / "motion-spec.json"
@@ -138,6 +156,66 @@ def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = F
             except (OSError, ValueError, AttributeError) as exc:
                 issues.append(f"asset provenance contract: {exc}")
 
+    consistency_name = manifest.get("consistency_ref")
+    if require_asset_consistency and not isinstance(consistency_name, str) and asset_consistency_path is None:
+        issues.append("asset consistency gate requires manifest.consistency_ref")
+    if consistency_name or asset_consistency_path:
+        resolved_consistency = asset_consistency_path or (scene_dir / str(consistency_name)).resolve()
+        if scene_dir.resolve() not in resolved_consistency.parents or not resolved_consistency.is_file():
+            issues.append("manifest.consistency_ref must point to an existing file inside the scene directory")
+        else:
+            try:
+                consistency_kind = manifest.get("consistency_kind", "frame-geometry")
+                consistency_module = _load_asset_consistency()
+                consistency_document = _json(resolved_consistency)
+                consistency_result = consistency_module.run(
+                    consistency_kind,
+                    consistency_document,
+                    scene_dir,
+                    strict=require_asset_consistency,
+                )
+                issues.extend(
+                    f"asset consistency: {item.get('code', 'issue')} — {item.get('message', 'contract violation')}"
+                    for item in consistency_result.get("errors", [])
+                )
+                if require_asset_consistency and not consistency_result.get("ready"):
+                    issues.append("asset consistency contract is not ready")
+            except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+                issues.append(f"asset consistency contract: {exc}")
+
+    intake = manifest.get("artifact_intake")
+    if require_artifact_intake and not isinstance(intake, dict):
+        issues.append("artifact intake gate requires manifest.artifact_intake")
+    if intake is not None:
+        required_intake_keys = ("registry", "receipt", "controls", "export_manifest")
+        if not isinstance(intake, dict) or any(not isinstance(intake.get(key), str) for key in required_intake_keys):
+            issues.append("manifest.artifact_intake requires registry, receipt, controls and export_manifest relative paths")
+        else:
+            resolved_intake = {key: (scene_dir / intake[key]).resolve() for key in required_intake_keys}
+            if any(scene_dir.resolve() not in path.parents or not path.is_file() for path in resolved_intake.values()):
+                issues.append("manifest.artifact_intake paths must point to existing files inside the scene directory")
+            else:
+                try:
+                    intake_module = _load_artifact_intake()
+                    intake_result = intake_module.evaluate_bundle(
+                        argparse.Namespace(
+                            root=scene_dir,
+                            registry=resolved_intake["registry"],
+                            receipt=resolved_intake["receipt"],
+                            controls=resolved_intake["controls"],
+                            export_manifest=resolved_intake["export_manifest"],
+                            strict=require_artifact_intake,
+                        )
+                    )
+                    issues.extend(
+                        f"artifact intake: {item.get('code', 'issue')} — {item.get('message', 'contract violation')}"
+                        for item in intake_result.get("errors", [])
+                    )
+                    if require_artifact_intake and not intake_result.get("ready"):
+                        issues.append("artifact intake contract is not runtime-ready")
+                except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+                    issues.append(f"artifact intake contract: {exc}")
+
     checks = manifest.get("checks")
     if not isinstance(checks, list) or not checks:
         issues.append("manifest.checks must contain the Dev Lab quality checklist")
@@ -414,6 +492,9 @@ def main() -> int:
     parser.add_argument("--require-visual-truth", action="store_true")
     parser.add_argument("--require-asset-provenance", action="store_true")
     parser.add_argument("--asset-provenance")
+    parser.add_argument("--require-asset-consistency", action="store_true")
+    parser.add_argument("--asset-consistency")
+    parser.add_argument("--require-artifact-intake", action="store_true")
     parser.add_argument("--attestation")
     parser.add_argument("--trust-policy")
     args = parser.parse_args()
@@ -429,13 +510,14 @@ def main() -> int:
     attestation_path = Path(args.attestation).resolve() if args.attestation else None
     trust_policy_path = Path(args.trust_policy).resolve() if args.trust_policy else None
     asset_provenance_path = Path(args.asset_provenance).resolve() if args.asset_provenance else None
+    asset_consistency_path = Path(args.asset_consistency).resolve() if args.asset_consistency else None
     scenes = [root / "src" / "output" / args.scene] if args.scene else sorted(p for p in output_root.iterdir() if p.is_dir()) if output_root.exists() else []
     if not scenes:
         print("QUALITY GATE: no scene outputs found")
         return 0
     failed = False
     for scene_dir in scenes:
-        issues = validate_scene(scene_dir, context, args.require_browser_review, task_dir, args.require_intelligence, args.require_p1, args.require_benchmark, args.require_telemetry, args.require_attestation, attestation_path, trust_policy_path, args.require_visual_truth, args.require_asset_provenance, asset_provenance_path)
+        issues = validate_scene(scene_dir, context, args.require_browser_review, task_dir, args.require_intelligence, args.require_p1, args.require_benchmark, args.require_telemetry, args.require_attestation, attestation_path, trust_policy_path, args.require_visual_truth, args.require_asset_provenance, asset_provenance_path, args.require_asset_consistency, asset_consistency_path, args.require_artifact_intake)
         if issues:
             failed = True
             print(f"REJECTED {scene_dir.name}:")
@@ -447,6 +529,10 @@ def main() -> int:
                 suffixes.append("visual-truth contract")
             if args.require_asset_provenance:
                 suffixes.append("asset provenance production eligibility")
+            if args.require_asset_consistency:
+                suffixes.append("asset consistency contract")
+            if args.require_artifact_intake:
+                suffixes.append("runtime-ready artifact intake")
             suffix = f" + {' + '.join(suffixes)}" if suffixes else ""
             print(f"ACCEPTED {scene_dir.name}: context + spec + runtime snapshots + browser-review candidate + checklist{suffix}")
     return 1 if failed else 0

package/scripts/report.py

@@ -63,6 +63,24 @@ def asset_provenance_module():
     return module
 
 
+def asset_consistency_module():
+    path = ROOT / "scripts" / "asset-consistency.py"
+    loader = importlib.util.spec_from_file_location("motionloom_asset_consistency", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
+def artifact_intake_module():
+    path = ROOT / "scripts" / "artifact-intake.py"
+    loader = importlib.util.spec_from_file_location("motionloom_artifact_intake", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
 def asset_provenance_result(scene_manifest_path: Path, scene_manifest: dict, mode: str = "runtime") -> dict:
     name = scene_manifest.get("asset_provenance")
     if not name:
@@ -81,6 +99,44 @@ def asset_provenance_result(scene_manifest_path: Path, scene_manifest: dict, mod
         return {"status": "fail", "errors": [f"asset provenance contract: {exc}"]}
 
 
+def asset_consistency_result(scene_manifest_path: Path, scene_manifest: dict, strict: bool = False) -> dict:
+    name = scene_manifest.get("consistency_ref")
+    if not name:
+        return {"status": "not-run", "ready": False, "errors": []}
+    scene_dir = scene_manifest_path.parent.resolve()
+    consistency_path = (scene_dir / str(name)).resolve()
+    if scene_dir not in consistency_path.parents or not consistency_path.is_file():
+        return {"status": "fail", "ready": False, "errors": ["scene manifest consistency_ref points to a missing or unsafe artifact"]}
+    try:
+        document = read_json(consistency_path)
+        kind = scene_manifest.get("consistency_kind", "frame-geometry")
+        result = asset_consistency_module().run(kind, document, scene_dir, strict=strict)
+        result["status"] = "pass" if result.get("ready") else "fail"
+        return result
+    except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+        return {"status": "fail", "ready": False, "errors": [f"asset consistency contract: {exc}"]}
+
+
+def artifact_intake_result(scene_manifest_path: Path, scene_manifest: dict, strict: bool = False) -> dict:
+    intake = scene_manifest.get("artifact_intake")
+    if not intake:
+        return {"status": "not-run", "ready": False, "errors": []}
+    required = ("registry", "receipt", "controls", "export_manifest")
+    scene_dir = scene_manifest_path.parent.resolve()
+    if not isinstance(intake, dict) or any(not isinstance(intake.get(key), str) for key in required):
+        return {"status": "fail", "ready": False, "errors": ["scene manifest artifact_intake is incomplete"]}
+    paths = {key: (scene_dir / intake[key]).resolve() for key in required}
+    if any(scene_dir not in path.parents or not path.is_file() for path in paths.values()):
+        return {"status": "fail", "ready": False, "errors": ["scene manifest artifact_intake points to a missing or unsafe artifact"]}
+    try:
+        result = artifact_intake_module().evaluate_bundle(
+            argparse.Namespace(root=scene_dir, registry=paths["registry"], receipt=paths["receipt"], controls=paths["controls"], export_manifest=paths["export_manifest"], strict=strict)
+        )
+        return result
+    except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+        return {"status": "fail", "ready": False, "errors": [f"artifact intake contract: {exc}"]}
+
+
 def memory_summary() -> dict | None:
     path = project_memory_path()
     if not path.is_file():
@@ -475,6 +531,18 @@ def check_report(args: argparse.Namespace) -> int:
             errors.append("ready-for-PR or confirmed task requires a passing asset provenance production check")
         elif not provenance.get("summary", {}).get("production_eligible"):
             errors.append("ready-for-PR or confirmed task requires asset provenance production_eligible")
+    consistency = asset_consistency_result(scene_manifest_path, scene_manifest, strict=state in {"ready_for_pr", "confirmed"})
+    if consistency.get("status") == "fail":
+        errors.extend(f"asset consistency: {error}" for error in consistency.get("errors", []))
+    if state in {"ready_for_pr", "confirmed"} and scene_manifest_path.is_file() and scene_manifest.get("consistency_ref"):
+        if consistency.get("status") != "pass" or not consistency.get("ready"):
+            errors.append("ready-for-PR or confirmed task requires a passing asset consistency contract")
+    intake = artifact_intake_result(scene_manifest_path, scene_manifest, strict=state in {"ready_for_pr", "confirmed"})
+    if intake.get("status") == "fail":
+        errors.extend(f"artifact intake: {error}" for error in intake.get("errors", []))
+    if state in {"ready_for_pr", "confirmed"} and scene_manifest_path.is_file() and scene_manifest.get("artifact_intake"):
+        if intake.get("status") != "pass" or not intake.get("ready"):
+            errors.append("ready-for-PR or confirmed task requires a runtime-ready artifact intake contract")
     if state in {"validated", "ready_for_pr", "confirmed"}:
         quality = read_json(task_dir / "quality-report.json")
         if quality.get("status") != "pass":
@@ -576,6 +644,18 @@ def render(args: argparse.Namespace) -> int:
         scene_manifest,
         "production" if task.get("state") in {"ready_for_pr", "confirmed"} else "runtime",
     )
+    consistency = asset_consistency_result(
+        ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json",
+        scene_manifest,
+        strict=task.get("state") in {"ready_for_pr", "confirmed"},
+    )
+    intake = artifact_intake_result(
+        ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json",
+        scene_manifest,
+        strict=task.get("state") in {"ready_for_pr", "confirmed"},
+    )
+    intake_adapter = intake.get("adapter") or {}
+    intake_evidence = intake.get("evidence") or {}
     lines = [
         f"# Animation Task Report — {task.get('task_id', task_dir.name)}",
         "",
@@ -609,6 +689,11 @@ def render(args: argparse.Namespace) -> int:
         "## Asset provenance",
         f"- Status: **{provenance.get('status', 'not-run')}**; authority: **{provenance.get('summary', {}).get('authority', 'unknown')}**; declared readiness: **{provenance.get('summary', {}).get('declared_readiness', 'blocked')}**; effective readiness: **{provenance.get('summary', {}).get('effective_readiness', 'blocked')}**",
         f"- Production eligible: **{provenance.get('summary', {}).get('production_eligible', False)}**; production approved: **{provenance.get('summary', {}).get('production_approved', False)}**; errors: **{len(provenance.get('errors', []))}**",
+        "## Asset consistency",
+        f"- Status: **{consistency.get('status', 'not-run')}**; contract: **{consistency.get('contract', scene_manifest.get('consistency_kind', 'not-declared'))}**; ready: **{consistency.get('ready', False)}**; errors: **{len(consistency.get('errors', []))}**; warnings: **{len(consistency.get('warnings', []))}**",
+        "## Artifact Intake",
+        f"- Status: **{intake.get('status', 'not-run')}**; adapter: **{intake_adapter.get('adapter_id', 'not-declared')}**; adapter status: **{intake_adapter.get('status', 'not-declared')}**; ready: **{intake.get('ready', False)}**; production eligible: **{intake.get('production_eligible', False)}**; production approved: **{intake.get('production_approved', False)}**",
+        f"- Receipt: `{intake_evidence.get('receipt', '')}`; controls: `{intake_evidence.get('controls', '')}`; export: `{intake_evidence.get('export_manifest', '')}`; errors: **{len(intake.get('errors', []))}**; warnings: **{len(intake.get('warnings', []))}**",
         "## Semantic motion lint",
         f"- Status: **{lint.get('status', 'not-run')}**; errors: **{lint.get('summary', {}).get('errors', 0)}**; warnings: **{lint.get('summary', {}).get('warnings', 0)}**; blocking: **{lint.get('summary', {}).get('blocking', 0)}**",
         md_table(lint.get("findings", []), [("Rule", "rule_id"), ("Severity", "severity"), ("Confidence", "confidence"), ("Message", "message"), ("Basis", "basis")]),

package/scripts/resolve-task-bundle.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Resolve one safe artifact task bundle bound to a scene identity.
+
+The resolver intentionally does not infer a task path from a scene slug. A
+bundle is eligible only when its direct ``artifacts/<task-id>/task.json``
+declares the requested scene and remains inside the repository artifacts root.
+Multiple matching bundles are rejected rather than ranked implicitly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def has_symlink_component(path: Path, root: Path) -> bool:
+    current = path
+    while True:
+        if current.is_symlink():
+            return True
+        if current == root:
+            return False
+        if current == current.parent:
+            return True
+        current = current.parent
+
+
+def resolve_task_dirs(root: Path, scene: str) -> list[Path]:
+    artifacts = root / "artifacts"
+    if not artifacts.is_dir() or artifacts.is_symlink():
+        return []
+    resolved_artifacts = artifacts.resolve()
+    matches: list[Path] = []
+    for task_path in sorted(artifacts.glob("*/task.json")):
+        if has_symlink_component(task_path, root):
+            continue
+        try:
+            if not task_path.resolve().is_relative_to(resolved_artifacts):
+                continue
+        except (OSError, RuntimeError):
+            continue
+        if read_json(task_path).get("scene") == scene:
+            matches.append(task_path.parent)
+    return matches
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--scene", required=True)
+    parser.add_argument("--root", default=".")
+    args = parser.parse_args()
+    if not SAFE_SCENE.fullmatch(args.scene) or args.scene in {".", ".."}:
+        print("FAIL: unsafe scene identifier", file=sys.stderr)
+        return 2
+
+    root = Path(args.root).resolve()
+    matches = resolve_task_dirs(root, args.scene)
+    if not matches:
+        print(f"FAIL: no safe task bundle bound to scene: {args.scene}", file=sys.stderr)
+        return 3
+    if len(matches) != 1:
+        joined = ", ".join(str(path.relative_to(root)) for path in matches)
+        print(f"FAIL: ambiguous task bundles bound to scene {args.scene}: {joined}", file=sys.stderr)
+        return 4
+    print(matches[0].relative_to(root).as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/review-hook.py

@@ -12,7 +12,7 @@ import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlsplit, urlunsplit
 
 ROOT = Path(__file__).resolve().parents[1]
 SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
@@ -42,6 +42,29 @@ def candidate_id(task_id: str, scene: str, context_hash: str, source_hash: str,
     return hashlib.sha256(raw).hexdigest()[:20]
 
 
+def review_urls(lab_url: str, scene: str, task_id: str, candidate: str) -> tuple[str, str, str]:
+    """Build an exact review route while anchoring artifact paths at its origin.
+
+    `--lab-url` is the actual browser route, e.g. `https://host/lab` for the
+    React Dev Lab or `http://127.0.0.1:3300/` for the bundled static lab.
+    Artifact and task paths intentionally remain same-origin root paths.
+    """
+    parsed = urlsplit(lab_url.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.query or parsed.fragment:
+        raise ValueError("lab-url must be an absolute http(s) Dev Lab route without query or fragment")
+    origin = urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+    review_path = parsed.path.rstrip("/") or "/"
+    review_base = f"{origin}{review_path}" if review_path != "/" else origin
+    query = urlencode({
+        "scene": scene,
+        "task_id": task_id,
+        "candidate_id": candidate,
+        "artifact_base": f"{origin}/scenes/{scene}",
+        "task_base": f"{origin}/tasks/{task_id}",
+    })
+    return f"{review_base}/?{query}" if review_path != "/" else f"{origin}/?{query}", f"{origin}/scenes/{scene}", f"{origin}/tasks/{task_id}"
+
+
 def paths(task_dir: Path, task: dict) -> tuple[Path, Path, Path, Path]:
     scene = task.get("scene", "")
     if not scene or scene in {".", ".."} or not SAFE_SCENE.fullmatch(scene):
@@ -79,9 +102,8 @@ def prepare(args: argparse.Namespace) -> int:
     source_hash = sha256(source_path)
     render_hash = sha256(render_meta)
     cid = candidate_id(task["task_id"], scene, context_hash, source_hash, render_hash)
-    base = args.lab_url.rstrip("/")
     task_id = task["task_id"]
-    url = f"{base}/?{urlencode({'scene': scene, 'task_id': task_id, 'candidate_id': cid, 'artifact_base': f'{base}/scenes/{scene}', 'task_base': f'{base}/tasks/{task_id}'})}"
+    url, artifact_base, task_base = review_urls(args.lab_url, scene, task_id, cid)
     candidate = {
         "schema_version": "1.0",
         "candidate_id": cid,
@@ -120,7 +142,7 @@ def prepare(args: argparse.Namespace) -> int:
     handoff = read_json(handoff_path)
     if memory_path.is_file():
         shutil.copy2(memory_path, task_dir / "project-memory.json")
-    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"] + (["project-memory.json"] if memory_path.is_file() else [])))})
+    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "artifact_base": artifact_base, "task_base": task_base, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"] + (["project-memory.json"] if memory_path.is_file() else [])))})
     handoff_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     subprocess.run([sys.executable, str(ROOT / "scripts/devlab.py"), scene, "--prepare-only", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
     subprocess.run([sys.executable, str(ROOT / "scripts/report.py"), "collect", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)