@harmonyos-arkts/d2h 0.1.10 → 0.1.12

package/skills/d2h-utg-ai-generate/scripts/utg_common.py

@@ -1,524 +1,524 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import heapq
-import json
-import os
-import re
-import tempfile
-from collections import Counter, defaultdict
-from pathlib import Path
-from typing import Any
-
-LOCATION_RE = re.compile(r"^(?P<path>.+):(?P<line>[1-9][0-9]*)$")
-CONFIDENCE_NAMES = {"high": 0.9, "medium": 0.6, "low": 0.3}
-ENTRY_MECHANISMS = {"deep-link", "app-link", "universal-link"}
-
-
-class UtgError(ValueError):
-    pass
-
-
-def load_json(path: Path) -> dict[str, Any]:
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise UtgError(f"cannot read JSON {path}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise UtgError(f"JSON root must be an object: {path}")
-    return value
-
-
-def atomic_write_json(path: Path, value: Any) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            json.dump(value, handle, ensure_ascii=False, indent=2)
-            handle.write("\n")
-        os.replace(temp_name, path)
-    except Exception:
-        try:
-            os.unlink(temp_name)
-        except FileNotFoundError:
-            pass
-        raise
-
-
-def _required_string(obj: dict[str, Any], key: str, where: str) -> str:
-    value = obj.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise UtgError(f"{where}.{key} must be a non-empty string")
-    return value.strip()
-
-
-def normalize_location(value: Any, project_root: Path, where: str) -> str:
-    if not isinstance(value, str):
-        raise UtgError(f"{where} must be a project-relative file:line string")
-    match = LOCATION_RE.match(value.strip())
-    if not match:
-        raise UtgError(f"{where} must end in :<positive-line>: {value!r}")
-    source = Path(match.group("path"))
-    line = int(match.group("line"))
-    root = project_root.resolve()
-    full = source.resolve() if source.is_absolute() else (root / source).resolve()
-    try:
-        relative = full.relative_to(root)
-    except ValueError as exc:
-        raise UtgError(f"{where} escapes project root: {value!r}") from exc
-    if not full.is_file():
-        raise UtgError(f"{where} source file does not exist: {relative.as_posix()}")
-    with full.open("r", encoding="utf-8", errors="replace") as handle:
-        line_count = sum(1 for _ in handle)
-    if line > line_count:
-        raise UtgError(
-            f"{where} line {line} exceeds {relative.as_posix()} line count {line_count}"
-        )
-    return f"{relative.as_posix()}:{line}"
-
-
-def normalize_confidence(value: Any, where: str, normalizations: list[str]) -> float:
-    if isinstance(value, bool):
-        raise UtgError(f"{where} must be a number in [0, 1]")
-    if isinstance(value, str) and value.lower() in CONFIDENCE_NAMES:
-        normalized = CONFIDENCE_NAMES[value.lower()]
-        normalizations.append(f"{where}: {value!r} -> {normalized}")
-        return normalized
-    if not isinstance(value, (int, float)) or not 0 <= float(value) <= 1:
-        raise UtgError(f"{where} must be a number in [0, 1]")
-    return float(value)
-
-
-def normalize_facts(
-    facts: dict[str, Any], project_root: Path
-) -> tuple[dict[str, Any], list[str], list[dict[str, Any]]]:
-    if facts.get("schema_version") != "d2h-utg-facts/v1":
-        raise UtgError("schema_version must be 'd2h-utg-facts/v1'")
-    graph_in = facts.get("graph")
-    if not isinstance(graph_in, dict):
-        raise UtgError("graph must be an object")
-    graph = dict(graph_in)
-    for key in ("app", "architecture", "root"):
-        graph[key] = _required_string(graph, key, "graph")
-    for key in ("package", "start_destination"):
-        if key in graph and not isinstance(graph[key], str):
-            raise UtgError(f"graph.{key} must be a string")
-
-    node_inputs = facts.get("nodes")
-    edge_inputs = facts.get("edges")
-    unresolved = facts.get("unresolved", [])
-    if not isinstance(node_inputs, list) or not node_inputs:
-        raise UtgError("nodes must be a non-empty array")
-    if not isinstance(edge_inputs, list):
-        raise UtgError("edges must be an array")
-    if not isinstance(unresolved, list):
-        raise UtgError("unresolved must be an array")
-
-    nodes: list[dict[str, Any]] = []
-    ids: set[str] = set()
-    normalizations: list[str] = []
-    for index, raw in enumerate(node_inputs):
-        where = f"nodes[{index}]"
-        if not isinstance(raw, dict):
-            raise UtgError(f"{where} must be an object")
-        node_id = _required_string(raw, "id", where)
-        if node_id in ids:
-            raise UtgError(f"duplicate node id: {node_id}")
-        ids.add(node_id)
-        node = {
-            "id": node_id,
-            "kind": _required_string(raw, "kind", where),
-            "label": _required_string(raw, "label", where),
-            "declared_at": normalize_location(
-                raw.get("declared_at"), project_root, f"{where}.declared_at"
-            ),
-            "status": raw.get("status", "static-only"),
-            "provenance": raw.get("provenance", "ai-source-analysis"),
-            "widgets": raw.get("widgets", []),
-            "expected": raw.get("expected", {}),
-            "required_state": raw.get("required_state", []),
-            "extra": raw.get("extra"),
-        }
-        if not isinstance(node["status"], str) or not node["status"]:
-            raise UtgError(f"{where}.status must be a non-empty string")
-        if not isinstance(node["provenance"], str) or not node["provenance"]:
-            raise UtgError(f"{where}.provenance must be a non-empty string")
-        if not isinstance(node["widgets"], list):
-            raise UtgError(f"{where}.widgets must be an array")
-        if not isinstance(node["expected"], dict):
-            raise UtgError(f"{where}.expected must be an object")
-        if not isinstance(node["required_state"], list) or not all(
-            isinstance(item, str) and item for item in node["required_state"]
-        ):
-            raise UtgError(f"{where}.required_state must be an array of strings")
-        if len(set(node["required_state"])) != len(node["required_state"]):
-            raise UtgError(f"{where}.required_state contains duplicates")
-        if node["extra"] is not None and not isinstance(node["extra"], dict):
-            raise UtgError(f"{where}.extra must be null or an object")
-        nodes.append(node)
-
-    if graph["root"] not in ids:
-        raise UtgError(f"graph.root references missing node: {graph['root']}")
-
-    links: list[dict[str, Any]] = []
-    keys: defaultdict[tuple[str, str], int] = defaultdict(int)
-    for index, raw in enumerate(edge_inputs):
-        where = f"edges[{index}]"
-        if not isinstance(raw, dict):
-            raise UtgError(f"{where} must be an object")
-        source = _required_string(raw, "source", where)
-        target = _required_string(raw, "target", where)
-        if source not in ids or target not in ids:
-            raise UtgError(f"{where} references missing node: {source} -> {target}")
-        guard = raw.get("guard")
-        if guard is not None:
-            if not isinstance(guard, dict):
-                raise UtgError(f"{where}.guard must be null or an object")
-            _required_string(guard, "kind", f"{where}.guard")
-            _required_string(guard, "text", f"{where}.guard")
-        args = raw.get("args", {})
-        if not isinstance(args, dict):
-            raise UtgError(f"{where}.args must be an object")
-        if "label_ambiguous" in args and not isinstance(args["label_ambiguous"], bool):
-            raise UtgError(f"{where}.args.label_ambiguous must be boolean")
-        pair = (source, target)
-        link = {
-            "source": source,
-            "target": target,
-            "mechanism": _required_string(raw, "mechanism", where),
-            "trigger": normalize_location(
-                raw.get("trigger"), project_root, f"{where}.trigger"
-            ),
-            "guard": guard,
-            "args": args,
-            "confidence": normalize_confidence(
-                raw.get("confidence"), f"{where}.confidence", normalizations
-            ),
-            "provenance": raw.get("provenance", "ai-source-analysis"),
-            "key": keys[pair],
-            "status": raw.get("status", "static-only"),
-        }
-        keys[pair] += 1
-        if "id" in raw:
-            link["id"] = _required_string(raw, "id", where)
-        if not isinstance(link["provenance"], str) or not link["provenance"]:
-            raise UtgError(f"{where}.provenance must be a non-empty string")
-        if not isinstance(link["status"], str) or not link["status"]:
-            raise UtgError(f"{where}.status must be a non-empty string")
-        links.append(link)
-
-    return {
-        "directed": True,
-        "multigraph": True,
-        "graph": graph,
-        "nodes": nodes,
-        "links": links,
-    }, normalizations, unresolved
-
-
-def replay_action_reason(step: dict[str, Any]) -> str | None:
-    """Shared executable-operand checks for path selection and page planning."""
-    action = step.get('action', 'tap')
-    selector = step.get('selector') or {}
-    ready = isinstance(selector, dict) and any(
-        (isinstance(selector.get(key), str) and bool(selector[key]))
-        or (isinstance(selector.get(key), list) and bool(selector[key])
-            and all(isinstance(value, str) and value for value in selector[key]))
-        for key in ('text', 'text_any', 'content_desc', 'content_desc_any', 'resource_id', 'resource_id_any'))
-    if action in {'tap', 'long-press'} and not ready and not (
-        step.get('label') and step.get('label_source') in {'string', 'content-description', 'system'}
-        and not step.get('label_ambiguous')):
-        return 'missing-executable-selector'
-    if action not in {'launch', 'start-activity', 'deep-link', 'home', 'back', 'default', 'tap', 'swipe', 'long-press'}:
-        return 'unsupported-replay-action'
-    if action == 'start-activity' and not re.fullmatch(r'[\w.]+/[\w.$]+', step.get('component', '')):
-        return 'missing-launch-component'
-    if action == 'deep-link' and not re.match(r'^[a-z][a-z0-9+.-]*:', step.get('label') or '', re.I):
-        return 'missing-entry-uri'
-    if action == 'swipe' and not step.get('direction'):
-        return 'missing-swipe-direction'
-    return None
-
-
-def _shortest_paths(
-    root: str, links: list[dict[str, Any]], allow_entry_edges: bool, prefer_executable: bool = False
-) -> dict[str, tuple[str, dict[str, Any]]]:
-    adjacency: defaultdict[str, list[tuple[int, dict[str, Any]]]] = defaultdict(list)
-    for index, edge in enumerate(links):
-        if edge["mechanism"] in ENTRY_MECHANISMS and not allow_entry_edges:
-            continue
-        adjacency[edge["source"]].append((index, edge))
-
-    # Runtime replay must prefer a universally executable path over a shorter
-    # guarded path.  Keeping guards first also preserves the guarded edge in
-    # the graph instead of forcing callers to delete a true source fact merely
-    # to obtain a replayable click path.
-    best = {root: (0, 0, 0, 0, ())}
-    previous: dict[str, tuple[str, dict[str, Any]]] = {}
-    queue = [(0, 0, 0, 0, (), root)]
-    while queue:
-        unready, guarded, entries, hops, order_path, source = heapq.heappop(queue)
-        if best.get(source) != (unready, guarded, entries, hops, order_path):
-            continue
-        for index, edge in adjacency.get(source, []):
-            target = edge["target"]
-            candidate = (
-                unready + (int(replay_action_reason(edge.get('args') or {}) is not None) if prefer_executable else 0),
-                guarded + (1 if edge.get("guard") else 0),
-                entries + (int(edge['mechanism'] in ENTRY_MECHANISMS) if prefer_executable else 0),
-                hops + 1,
-                order_path + (index,),
-            )
-            if target not in best or candidate < best[target]:
-                best[target] = candidate
-                previous[target] = (source, edge)
-                heapq.heappush(queue, (*candidate, target))
-    return previous
-
-
-def _reconstruct(
-    target: str, root: str, previous: dict[str, tuple[str, dict[str, Any]]]
-) -> list[dict[str, Any]] | None:
-    if target == root:
-        return []
-    edges: list[dict[str, Any]] = []
-    current = target
-    seen: set[str] = set()
-    while current != root:
-        if current in seen or current not in previous:
-            return None
-        seen.add(current)
-        source, edge = previous[current]
-        edges.append(edge)
-        current = source
-    edges.reverse()
-    return edges
-
-
-def build_click_paths(utg: dict[str, Any]) -> dict[str, Any]:
-    root = utg["graph"]["root"]
-    kinds = {node["id"]: node["kind"] for node in utg["nodes"]}
-    prefer_executable = utg['graph'].get('path_policy') == 'source-executable-first'
-    normal = _shortest_paths(root, utg["links"], allow_entry_edges=prefer_executable, prefer_executable=prefer_executable)
-    with_entries = _shortest_paths(root, utg["links"], allow_entry_edges=True, prefer_executable=prefer_executable)
-    paths: dict[str, Any] = {}
-    unreachable: list[str] = []
-
-    for node in utg["nodes"]:
-        node_id = node["id"]
-        edges = _reconstruct(node_id, root, normal)
-        if edges is None:
-            edges = _reconstruct(node_id, root, with_entries)
-        if edges is None:
-            unreachable.append(node_id)
-            continue
-        steps: list[dict[str, Any]] = [
-            {
-                "action": "launch",
-                "label": None,
-                "target_id": root,
-                "target_kind": kinds[root],
-                "guard": None,
-            }
-        ]
-        labels: list[str] = []
-        for edge in edges:
-            args = edge.get("args") or {}
-            label = args.get("label")
-            step: dict[str, Any] = {
-                "action": args.get("action", "tap"),
-                "label": label if isinstance(label, str) else None,
-                "label_source": args.get("label_source"),
-                "label_ambiguous": bool(args.get("label_ambiguous", False)),
-                "target_id": edge["target"],
-                "target_kind": kinds[edge["target"]],
-                "guard": edge.get("guard"),
-                "mechanism": edge["mechanism"],
-            }
-            if isinstance(args.get("nl_hint"), str) and args["nl_hint"]:
-                step["nl_hint"] = args["nl_hint"]
-            for key in ("selector", "direction", "distance", "duration_ms", "max_scrolls", "component"):
-                if key in args:
-                    step[key] = args[key]
-            steps.append(step)
-            if isinstance(label, str) and label:
-                labels.append(label)
-        depth = len(edges)
-        paths[node_id] = {
-            "depth": depth,
-            "steps": steps,
-            "labels": labels,
-            "clicks": depth,
-            "kind": kinds[node_id],
-            "path_text": " > ".join(labels) if labels else node_id,
-        }
-    return {"root": root, "paths": paths, "unreachable": unreachable}
-
-
-def validate_pair(
-    utg: dict[str, Any], click_paths: dict[str, Any], project_root: Path | None = None
-) -> list[str]:
-    errors: list[str] = []
-    if utg.get("directed") is not True:
-        errors.append("utg.directed must be true")
-    if utg.get("multigraph") is not True:
-        errors.append("utg.multigraph must be true")
-    graph = utg.get("graph")
-    nodes = utg.get("nodes")
-    links = utg.get("links")
-    if not isinstance(graph, dict):
-        return errors + ["utg.graph must be an object"]
-    if not isinstance(nodes, list) or not nodes:
-        return errors + ["utg.nodes must be a non-empty array"]
-    if not isinstance(links, list):
-        return errors + ["utg.links must be an array"]
-
-    ids: dict[str, dict[str, Any]] = {}
-    for index, node in enumerate(nodes):
-        where = f"nodes[{index}]"
-        if not isinstance(node, dict):
-            errors.append(f"{where} must be an object")
-            continue
-        node_id = node.get("id")
-        if not isinstance(node_id, str) or not node_id:
-            errors.append(f"{where}.id must be a non-empty string")
-            continue
-        if node_id in ids:
-            errors.append(f"duplicate node id: {node_id}")
-        ids[node_id] = node
-        for key, expected in (
-            ("kind", str), ("label", str), ("declared_at", str),
-            ("status", str), ("provenance", str), ("widgets", list),
-            ("expected", dict), ("required_state", list),
-        ):
-            if not isinstance(node.get(key), expected):
-                errors.append(f"{where}.{key} has wrong type")
-        if node.get("extra") is not None and not isinstance(node.get("extra"), dict):
-            errors.append(f"{where}.extra must be null or an object")
-        if project_root and isinstance(node.get("declared_at"), str):
-            try:
-                normalize_location(node["declared_at"], project_root, f"{where}.declared_at")
-            except UtgError as exc:
-                errors.append(str(exc))
-
-    root = graph.get("root")
-    if root not in ids:
-        errors.append(f"graph.root references missing node: {root!r}")
-
-    seen_keys: set[tuple[str, str, int]] = set()
-    edge_index: set[tuple[str, str, str]] = set()
-    for index, edge in enumerate(links):
-        where = f"links[{index}]"
-        if not isinstance(edge, dict):
-            errors.append(f"{where} must be an object")
-            continue
-        source, target = edge.get("source"), edge.get("target")
-        if source not in ids or target not in ids:
-            errors.append(f"{where} references missing node: {source!r} -> {target!r}")
-        mechanism = edge.get("mechanism")
-        if not isinstance(mechanism, str) or not mechanism:
-            errors.append(f"{where}.mechanism must be a non-empty string")
-        else:
-            edge_index.add((source, target, mechanism))
-        confidence = edge.get("confidence")
-        if isinstance(confidence, bool) or not isinstance(confidence, (int, float)) or not 0 <= confidence <= 1:
-            errors.append(f"{where}.confidence must be numeric in [0, 1]")
-        key = edge.get("key")
-        if not isinstance(key, int) or isinstance(key, bool) or key < 0:
-            errors.append(f"{where}.key must be a non-negative integer")
-        elif isinstance(source, str) and isinstance(target, str):
-            identity = (source, target, key)
-            if identity in seen_keys:
-                errors.append(f"duplicate parallel-edge identity: {identity}")
-            seen_keys.add(identity)
-        if not isinstance(edge.get("args"), dict):
-            errors.append(f"{where}.args must be an object")
-        guard = edge.get("guard")
-        if guard is not None and (
-            not isinstance(guard, dict)
-            or not isinstance(guard.get("kind"), str)
-            or not guard.get("kind")
-            or not isinstance(guard.get("text"), str)
-            or not guard.get("text")
-        ):
-            errors.append(f"{where}.guard must be null or contain kind/text")
-        if project_root and isinstance(edge.get("trigger"), str):
-            try:
-                normalize_location(edge["trigger"], project_root, f"{where}.trigger")
-            except UtgError as exc:
-                errors.append(str(exc))
-
-    if not isinstance(click_paths, dict):
-        return errors + ["click_paths root must be an object"]
-    if click_paths.get("root") != root:
-        errors.append("click_paths.root must equal utg.graph.root")
-    paths = click_paths.get("paths")
-    unreachable = click_paths.get("unreachable")
-    if not isinstance(paths, dict):
-        return errors + ["click_paths.paths must be an object"]
-    if not isinstance(unreachable, list) or not all(isinstance(item, str) for item in unreachable):
-        return errors + ["click_paths.unreachable must be an array of node ids"]
-    if len(set(unreachable)) != len(unreachable):
-        errors.append("click_paths.unreachable contains duplicates")
-    covered = set(paths) | set(unreachable)
-    if covered != set(ids):
-        errors.append(
-            "paths and unreachable must partition all nodes; "
-            f"missing={sorted(set(ids) - covered)}, extra={sorted(covered - set(ids))}"
-        )
-    if set(paths) & set(unreachable):
-        errors.append("a node cannot be both reachable and unreachable")
-
-    for node_id, path in paths.items():
-        where = f"paths[{node_id!r}]"
-        if node_id not in ids or not isinstance(path, dict):
-            continue
-        steps = path.get("steps")
-        labels = path.get("labels")
-        if not isinstance(steps, list) or not steps:
-            errors.append(f"{where}.steps must be a non-empty array")
-            continue
-        if steps[0].get("target_id") != root or steps[0].get("action") != "launch":
-            errors.append(f"{where} must start with launch to root")
-        if steps[-1].get("target_id") != node_id:
-            errors.append(f"{where} final step must target {node_id}")
-        depth = len(steps) - 1
-        if path.get("depth") != depth:
-            errors.append(f"{where}.depth must equal len(steps)-1")
-        if path.get("clicks") != depth:
-            errors.append(f"{where}.clicks must equal depth")
-        if path.get("kind") != ids[node_id].get("kind"):
-            errors.append(f"{where}.kind does not match node kind")
-        derived_labels = [
-            step.get("label") for step in steps[1:]
-            if isinstance(step.get("label"), str) and step.get("label")
-        ]
-        if labels != derived_labels:
-            errors.append(f"{where}.labels are not derived from steps")
-        expected_text = " > ".join(derived_labels) if derived_labels else node_id
-        if path.get("path_text") != expected_text:
-            errors.append(f"{where}.path_text is not derived from labels")
-        current = root
-        for step_index, step in enumerate(steps[1:], start=1):
-            target = step.get("target_id")
-            mechanism = step.get("mechanism")
-            if (current, target, mechanism) not in edge_index:
-                errors.append(
-                    f"{where}.steps[{step_index}] has no matching UTG edge: "
-                    f"{current!r} -> {target!r} via {mechanism!r}"
-                )
-            current = target
-    return errors
-
-
-def summary(utg: dict[str, Any], click_paths: dict[str, Any]) -> dict[str, Any]:
-    return {
-        "nodes": len(utg["nodes"]),
-        "nodes_by_kind": dict(sorted(Counter(n["kind"] for n in utg["nodes"]).items())),
-        "edges": len(utg["links"]),
-        "edges_by_mechanism": dict(
-            sorted(Counter(e["mechanism"] for e in utg["links"]).items())
-        ),
-        "reachable": len(click_paths["paths"]),
-        "unreachable": len(click_paths["unreachable"]),
-    }
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import heapq
+import json
+import os
+import re
+import tempfile
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+LOCATION_RE = re.compile(r"^(?P<path>.+):(?P<line>[1-9][0-9]*)$")
+CONFIDENCE_NAMES = {"high": 0.9, "medium": 0.6, "low": 0.3}
+ENTRY_MECHANISMS = {"deep-link", "app-link", "universal-link"}
+
+
+class UtgError(ValueError):
+    pass
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise UtgError(f"cannot read JSON {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise UtgError(f"JSON root must be an object: {path}")
+    return value
+
+
+def atomic_write_json(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, path)
+    except Exception:
+        try:
+            os.unlink(temp_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _required_string(obj: dict[str, Any], key: str, where: str) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise UtgError(f"{where}.{key} must be a non-empty string")
+    return value.strip()
+
+
+def normalize_location(value: Any, project_root: Path, where: str) -> str:
+    if not isinstance(value, str):
+        raise UtgError(f"{where} must be a project-relative file:line string")
+    match = LOCATION_RE.match(value.strip())
+    if not match:
+        raise UtgError(f"{where} must end in :<positive-line>: {value!r}")
+    source = Path(match.group("path"))
+    line = int(match.group("line"))
+    root = project_root.resolve()
+    full = source.resolve() if source.is_absolute() else (root / source).resolve()
+    try:
+        relative = full.relative_to(root)
+    except ValueError as exc:
+        raise UtgError(f"{where} escapes project root: {value!r}") from exc
+    if not full.is_file():
+        raise UtgError(f"{where} source file does not exist: {relative.as_posix()}")
+    with full.open("r", encoding="utf-8", errors="replace") as handle:
+        line_count = sum(1 for _ in handle)
+    if line > line_count:
+        raise UtgError(
+            f"{where} line {line} exceeds {relative.as_posix()} line count {line_count}"
+        )
+    return f"{relative.as_posix()}:{line}"
+
+
+def normalize_confidence(value: Any, where: str, normalizations: list[str]) -> float:
+    if isinstance(value, bool):
+        raise UtgError(f"{where} must be a number in [0, 1]")
+    if isinstance(value, str) and value.lower() in CONFIDENCE_NAMES:
+        normalized = CONFIDENCE_NAMES[value.lower()]
+        normalizations.append(f"{where}: {value!r} -> {normalized}")
+        return normalized
+    if not isinstance(value, (int, float)) or not 0 <= float(value) <= 1:
+        raise UtgError(f"{where} must be a number in [0, 1]")
+    return float(value)
+
+
+def normalize_facts(
+    facts: dict[str, Any], project_root: Path
+) -> tuple[dict[str, Any], list[str], list[dict[str, Any]]]:
+    if facts.get("schema_version") != "d2h-utg-facts/v1":
+        raise UtgError("schema_version must be 'd2h-utg-facts/v1'")
+    graph_in = facts.get("graph")
+    if not isinstance(graph_in, dict):
+        raise UtgError("graph must be an object")
+    graph = dict(graph_in)
+    for key in ("app", "architecture", "root"):
+        graph[key] = _required_string(graph, key, "graph")
+    for key in ("package", "start_destination"):
+        if key in graph and not isinstance(graph[key], str):
+            raise UtgError(f"graph.{key} must be a string")
+
+    node_inputs = facts.get("nodes")
+    edge_inputs = facts.get("edges")
+    unresolved = facts.get("unresolved", [])
+    if not isinstance(node_inputs, list) or not node_inputs:
+        raise UtgError("nodes must be a non-empty array")
+    if not isinstance(edge_inputs, list):
+        raise UtgError("edges must be an array")
+    if not isinstance(unresolved, list):
+        raise UtgError("unresolved must be an array")
+
+    nodes: list[dict[str, Any]] = []
+    ids: set[str] = set()
+    normalizations: list[str] = []
+    for index, raw in enumerate(node_inputs):
+        where = f"nodes[{index}]"
+        if not isinstance(raw, dict):
+            raise UtgError(f"{where} must be an object")
+        node_id = _required_string(raw, "id", where)
+        if node_id in ids:
+            raise UtgError(f"duplicate node id: {node_id}")
+        ids.add(node_id)
+        node = {
+            "id": node_id,
+            "kind": _required_string(raw, "kind", where),
+            "label": _required_string(raw, "label", where),
+            "declared_at": normalize_location(
+                raw.get("declared_at"), project_root, f"{where}.declared_at"
+            ),
+            "status": raw.get("status", "static-only"),
+            "provenance": raw.get("provenance", "ai-source-analysis"),
+            "widgets": raw.get("widgets", []),
+            "expected": raw.get("expected", {}),
+            "required_state": raw.get("required_state", []),
+            "extra": raw.get("extra"),
+        }
+        if not isinstance(node["status"], str) or not node["status"]:
+            raise UtgError(f"{where}.status must be a non-empty string")
+        if not isinstance(node["provenance"], str) or not node["provenance"]:
+            raise UtgError(f"{where}.provenance must be a non-empty string")
+        if not isinstance(node["widgets"], list):
+            raise UtgError(f"{where}.widgets must be an array")
+        if not isinstance(node["expected"], dict):
+            raise UtgError(f"{where}.expected must be an object")
+        if not isinstance(node["required_state"], list) or not all(
+            isinstance(item, str) and item for item in node["required_state"]
+        ):
+            raise UtgError(f"{where}.required_state must be an array of strings")
+        if len(set(node["required_state"])) != len(node["required_state"]):
+            raise UtgError(f"{where}.required_state contains duplicates")
+        if node["extra"] is not None and not isinstance(node["extra"], dict):
+            raise UtgError(f"{where}.extra must be null or an object")
+        nodes.append(node)
+
+    if graph["root"] not in ids:
+        raise UtgError(f"graph.root references missing node: {graph['root']}")
+
+    links: list[dict[str, Any]] = []
+    keys: defaultdict[tuple[str, str], int] = defaultdict(int)
+    for index, raw in enumerate(edge_inputs):
+        where = f"edges[{index}]"
+        if not isinstance(raw, dict):
+            raise UtgError(f"{where} must be an object")
+        source = _required_string(raw, "source", where)
+        target = _required_string(raw, "target", where)
+        if source not in ids or target not in ids:
+            raise UtgError(f"{where} references missing node: {source} -> {target}")
+        guard = raw.get("guard")
+        if guard is not None:
+            if not isinstance(guard, dict):
+                raise UtgError(f"{where}.guard must be null or an object")
+            _required_string(guard, "kind", f"{where}.guard")
+            _required_string(guard, "text", f"{where}.guard")
+        args = raw.get("args", {})
+        if not isinstance(args, dict):
+            raise UtgError(f"{where}.args must be an object")
+        if "label_ambiguous" in args and not isinstance(args["label_ambiguous"], bool):
+            raise UtgError(f"{where}.args.label_ambiguous must be boolean")
+        pair = (source, target)
+        link = {
+            "source": source,
+            "target": target,
+            "mechanism": _required_string(raw, "mechanism", where),
+            "trigger": normalize_location(
+                raw.get("trigger"), project_root, f"{where}.trigger"
+            ),
+            "guard": guard,
+            "args": args,
+            "confidence": normalize_confidence(
+                raw.get("confidence"), f"{where}.confidence", normalizations
+            ),
+            "provenance": raw.get("provenance", "ai-source-analysis"),
+            "key": keys[pair],
+            "status": raw.get("status", "static-only"),
+        }
+        keys[pair] += 1
+        if "id" in raw:
+            link["id"] = _required_string(raw, "id", where)
+        if not isinstance(link["provenance"], str) or not link["provenance"]:
+            raise UtgError(f"{where}.provenance must be a non-empty string")
+        if not isinstance(link["status"], str) or not link["status"]:
+            raise UtgError(f"{where}.status must be a non-empty string")
+        links.append(link)
+
+    return {
+        "directed": True,
+        "multigraph": True,
+        "graph": graph,
+        "nodes": nodes,
+        "links": links,
+    }, normalizations, unresolved
+
+
+def replay_action_reason(step: dict[str, Any]) -> str | None:
+    """Shared executable-operand checks for path selection and page planning."""
+    action = step.get('action', 'tap')
+    selector = step.get('selector') or {}
+    ready = isinstance(selector, dict) and any(
+        (isinstance(selector.get(key), str) and bool(selector[key]))
+        or (isinstance(selector.get(key), list) and bool(selector[key])
+            and all(isinstance(value, str) and value for value in selector[key]))
+        for key in ('text', 'text_any', 'content_desc', 'content_desc_any', 'resource_id', 'resource_id_any'))
+    if action in {'tap', 'long-press'} and not ready and not (
+        step.get('label') and step.get('label_source') in {'string', 'content-description', 'system'}
+        and not step.get('label_ambiguous')):
+        return 'missing-executable-selector'
+    if action not in {'launch', 'start-activity', 'deep-link', 'home', 'back', 'default', 'tap', 'swipe', 'long-press'}:
+        return 'unsupported-replay-action'
+    if action == 'start-activity' and not re.fullmatch(r'[\w.]+/[\w.$]+', step.get('component', '')):
+        return 'missing-launch-component'
+    if action == 'deep-link' and not re.match(r'^[a-z][a-z0-9+.-]*:', step.get('label') or '', re.I):
+        return 'missing-entry-uri'
+    if action == 'swipe' and not step.get('direction'):
+        return 'missing-swipe-direction'
+    return None
+
+
+def _shortest_paths(
+    root: str, links: list[dict[str, Any]], allow_entry_edges: bool, prefer_executable: bool = False
+) -> dict[str, tuple[str, dict[str, Any]]]:
+    adjacency: defaultdict[str, list[tuple[int, dict[str, Any]]]] = defaultdict(list)
+    for index, edge in enumerate(links):
+        if edge["mechanism"] in ENTRY_MECHANISMS and not allow_entry_edges:
+            continue
+        adjacency[edge["source"]].append((index, edge))
+
+    # Runtime replay must prefer a universally executable path over a shorter
+    # guarded path.  Keeping guards first also preserves the guarded edge in
+    # the graph instead of forcing callers to delete a true source fact merely
+    # to obtain a replayable click path.
+    best = {root: (0, 0, 0, 0, ())}
+    previous: dict[str, tuple[str, dict[str, Any]]] = {}
+    queue = [(0, 0, 0, 0, (), root)]
+    while queue:
+        unready, guarded, entries, hops, order_path, source = heapq.heappop(queue)
+        if best.get(source) != (unready, guarded, entries, hops, order_path):
+            continue
+        for index, edge in adjacency.get(source, []):
+            target = edge["target"]
+            candidate = (
+                unready + (int(replay_action_reason(edge.get('args') or {}) is not None) if prefer_executable else 0),
+                guarded + (1 if edge.get("guard") else 0),
+                entries + (int(edge['mechanism'] in ENTRY_MECHANISMS) if prefer_executable else 0),
+                hops + 1,
+                order_path + (index,),
+            )
+            if target not in best or candidate < best[target]:
+                best[target] = candidate
+                previous[target] = (source, edge)
+                heapq.heappush(queue, (*candidate, target))
+    return previous
+
+
+def _reconstruct(
+    target: str, root: str, previous: dict[str, tuple[str, dict[str, Any]]]
+) -> list[dict[str, Any]] | None:
+    if target == root:
+        return []
+    edges: list[dict[str, Any]] = []
+    current = target
+    seen: set[str] = set()
+    while current != root:
+        if current in seen or current not in previous:
+            return None
+        seen.add(current)
+        source, edge = previous[current]
+        edges.append(edge)
+        current = source
+    edges.reverse()
+    return edges
+
+
+def build_click_paths(utg: dict[str, Any]) -> dict[str, Any]:
+    root = utg["graph"]["root"]
+    kinds = {node["id"]: node["kind"] for node in utg["nodes"]}
+    prefer_executable = utg['graph'].get('path_policy') == 'source-executable-first'
+    normal = _shortest_paths(root, utg["links"], allow_entry_edges=prefer_executable, prefer_executable=prefer_executable)
+    with_entries = _shortest_paths(root, utg["links"], allow_entry_edges=True, prefer_executable=prefer_executable)
+    paths: dict[str, Any] = {}
+    unreachable: list[str] = []
+
+    for node in utg["nodes"]:
+        node_id = node["id"]
+        edges = _reconstruct(node_id, root, normal)
+        if edges is None:
+            edges = _reconstruct(node_id, root, with_entries)
+        if edges is None:
+            unreachable.append(node_id)
+            continue
+        steps: list[dict[str, Any]] = [
+            {
+                "action": "launch",
+                "label": None,
+                "target_id": root,
+                "target_kind": kinds[root],
+                "guard": None,
+            }
+        ]
+        labels: list[str] = []
+        for edge in edges:
+            args = edge.get("args") or {}
+            label = args.get("label")
+            step: dict[str, Any] = {
+                "action": args.get("action", "tap"),
+                "label": label if isinstance(label, str) else None,
+                "label_source": args.get("label_source"),
+                "label_ambiguous": bool(args.get("label_ambiguous", False)),
+                "target_id": edge["target"],
+                "target_kind": kinds[edge["target"]],
+                "guard": edge.get("guard"),
+                "mechanism": edge["mechanism"],
+            }
+            if isinstance(args.get("nl_hint"), str) and args["nl_hint"]:
+                step["nl_hint"] = args["nl_hint"]
+            for key in ("selector", "direction", "distance", "duration_ms", "max_scrolls", "component"):
+                if key in args:
+                    step[key] = args[key]
+            steps.append(step)
+            if isinstance(label, str) and label:
+                labels.append(label)
+        depth = len(edges)
+        paths[node_id] = {
+            "depth": depth,
+            "steps": steps,
+            "labels": labels,
+            "clicks": depth,
+            "kind": kinds[node_id],
+            "path_text": " > ".join(labels) if labels else node_id,
+        }
+    return {"root": root, "paths": paths, "unreachable": unreachable}
+
+
+def validate_pair(
+    utg: dict[str, Any], click_paths: dict[str, Any], project_root: Path | None = None
+) -> list[str]:
+    errors: list[str] = []
+    if utg.get("directed") is not True:
+        errors.append("utg.directed must be true")
+    if utg.get("multigraph") is not True:
+        errors.append("utg.multigraph must be true")
+    graph = utg.get("graph")
+    nodes = utg.get("nodes")
+    links = utg.get("links")
+    if not isinstance(graph, dict):
+        return errors + ["utg.graph must be an object"]
+    if not isinstance(nodes, list) or not nodes:
+        return errors + ["utg.nodes must be a non-empty array"]
+    if not isinstance(links, list):
+        return errors + ["utg.links must be an array"]
+
+    ids: dict[str, dict[str, Any]] = {}
+    for index, node in enumerate(nodes):
+        where = f"nodes[{index}]"
+        if not isinstance(node, dict):
+            errors.append(f"{where} must be an object")
+            continue
+        node_id = node.get("id")
+        if not isinstance(node_id, str) or not node_id:
+            errors.append(f"{where}.id must be a non-empty string")
+            continue
+        if node_id in ids:
+            errors.append(f"duplicate node id: {node_id}")
+        ids[node_id] = node
+        for key, expected in (
+            ("kind", str), ("label", str), ("declared_at", str),
+            ("status", str), ("provenance", str), ("widgets", list),
+            ("expected", dict), ("required_state", list),
+        ):
+            if not isinstance(node.get(key), expected):
+                errors.append(f"{where}.{key} has wrong type")
+        if node.get("extra") is not None and not isinstance(node.get("extra"), dict):
+            errors.append(f"{where}.extra must be null or an object")
+        if project_root and isinstance(node.get("declared_at"), str):
+            try:
+                normalize_location(node["declared_at"], project_root, f"{where}.declared_at")
+            except UtgError as exc:
+                errors.append(str(exc))
+
+    root = graph.get("root")
+    if root not in ids:
+        errors.append(f"graph.root references missing node: {root!r}")
+
+    seen_keys: set[tuple[str, str, int]] = set()
+    edge_index: set[tuple[str, str, str]] = set()
+    for index, edge in enumerate(links):
+        where = f"links[{index}]"
+        if not isinstance(edge, dict):
+            errors.append(f"{where} must be an object")
+            continue
+        source, target = edge.get("source"), edge.get("target")
+        if source not in ids or target not in ids:
+            errors.append(f"{where} references missing node: {source!r} -> {target!r}")
+        mechanism = edge.get("mechanism")
+        if not isinstance(mechanism, str) or not mechanism:
+            errors.append(f"{where}.mechanism must be a non-empty string")
+        else:
+            edge_index.add((source, target, mechanism))
+        confidence = edge.get("confidence")
+        if isinstance(confidence, bool) or not isinstance(confidence, (int, float)) or not 0 <= confidence <= 1:
+            errors.append(f"{where}.confidence must be numeric in [0, 1]")
+        key = edge.get("key")
+        if not isinstance(key, int) or isinstance(key, bool) or key < 0:
+            errors.append(f"{where}.key must be a non-negative integer")
+        elif isinstance(source, str) and isinstance(target, str):
+            identity = (source, target, key)
+            if identity in seen_keys:
+                errors.append(f"duplicate parallel-edge identity: {identity}")
+            seen_keys.add(identity)
+        if not isinstance(edge.get("args"), dict):
+            errors.append(f"{where}.args must be an object")
+        guard = edge.get("guard")
+        if guard is not None and (
+            not isinstance(guard, dict)
+            or not isinstance(guard.get("kind"), str)
+            or not guard.get("kind")
+            or not isinstance(guard.get("text"), str)
+            or not guard.get("text")
+        ):
+            errors.append(f"{where}.guard must be null or contain kind/text")
+        if project_root and isinstance(edge.get("trigger"), str):
+            try:
+                normalize_location(edge["trigger"], project_root, f"{where}.trigger")
+            except UtgError as exc:
+                errors.append(str(exc))
+
+    if not isinstance(click_paths, dict):
+        return errors + ["click_paths root must be an object"]
+    if click_paths.get("root") != root:
+        errors.append("click_paths.root must equal utg.graph.root")
+    paths = click_paths.get("paths")
+    unreachable = click_paths.get("unreachable")
+    if not isinstance(paths, dict):
+        return errors + ["click_paths.paths must be an object"]
+    if not isinstance(unreachable, list) or not all(isinstance(item, str) for item in unreachable):
+        return errors + ["click_paths.unreachable must be an array of node ids"]
+    if len(set(unreachable)) != len(unreachable):
+        errors.append("click_paths.unreachable contains duplicates")
+    covered = set(paths) | set(unreachable)
+    if covered != set(ids):
+        errors.append(
+            "paths and unreachable must partition all nodes; "
+            f"missing={sorted(set(ids) - covered)}, extra={sorted(covered - set(ids))}"
+        )
+    if set(paths) & set(unreachable):
+        errors.append("a node cannot be both reachable and unreachable")
+
+    for node_id, path in paths.items():
+        where = f"paths[{node_id!r}]"
+        if node_id not in ids or not isinstance(path, dict):
+            continue
+        steps = path.get("steps")
+        labels = path.get("labels")
+        if not isinstance(steps, list) or not steps:
+            errors.append(f"{where}.steps must be a non-empty array")
+            continue
+        if steps[0].get("target_id") != root or steps[0].get("action") != "launch":
+            errors.append(f"{where} must start with launch to root")
+        if steps[-1].get("target_id") != node_id:
+            errors.append(f"{where} final step must target {node_id}")
+        depth = len(steps) - 1
+        if path.get("depth") != depth:
+            errors.append(f"{where}.depth must equal len(steps)-1")
+        if path.get("clicks") != depth:
+            errors.append(f"{where}.clicks must equal depth")
+        if path.get("kind") != ids[node_id].get("kind"):
+            errors.append(f"{where}.kind does not match node kind")
+        derived_labels = [
+            step.get("label") for step in steps[1:]
+            if isinstance(step.get("label"), str) and step.get("label")
+        ]
+        if labels != derived_labels:
+            errors.append(f"{where}.labels are not derived from steps")
+        expected_text = " > ".join(derived_labels) if derived_labels else node_id
+        if path.get("path_text") != expected_text:
+            errors.append(f"{where}.path_text is not derived from labels")
+        current = root
+        for step_index, step in enumerate(steps[1:], start=1):
+            target = step.get("target_id")
+            mechanism = step.get("mechanism")
+            if (current, target, mechanism) not in edge_index:
+                errors.append(
+                    f"{where}.steps[{step_index}] has no matching UTG edge: "
+                    f"{current!r} -> {target!r} via {mechanism!r}"
+                )
+            current = target
+    return errors
+
+
+def summary(utg: dict[str, Any], click_paths: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "nodes": len(utg["nodes"]),
+        "nodes_by_kind": dict(sorted(Counter(n["kind"] for n in utg["nodes"]).items())),
+        "edges": len(utg["links"]),
+        "edges_by_mechanism": dict(
+            sorted(Counter(e["mechanism"] for e in utg["links"]).items())
+        ),
+        "reachable": len(click_paths["paths"]),
+        "unreachable": len(click_paths["unreachable"]),
+    }