ckgraphify 0.1.0__py3-none-any.whl

graphify/business_map.py

@@ -0,0 +1,1420 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from graphify.graph_main_trace import trace_graph_main
+
+
+_STATUS_ORDER = {"verified": 0, "candidate": 1, "partial": 2, "unexplored": 3, "stale": 4}
+_KG_BANKS_DIR_NAME = "kg-banks"
+_KG_BANKS_ROOT_MARKER = "__root__"
+
+
+@dataclass(frozen=True)
+class BusinessValidationResult:
+    concept_count: int
+    scenario_count: int
+    anchor_count: int
+    trace_hint_count: int
+    missing_anchors: list[dict]
+    missing_trace_refs: list[dict]
+
+    @property
+    def ok(self) -> bool:
+        return not self.missing_anchors and not self.missing_trace_refs
+
+
+@dataclass(frozen=True)
+class BusinessLintIssue:
+    level: str
+    path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class BusinessLintResult:
+    issues: list[BusinessLintIssue]
+
+    @property
+    def errors(self) -> list[BusinessLintIssue]:
+        return [issue for issue in self.issues if issue.level == "ERROR"]
+
+    @property
+    def warnings(self) -> list[BusinessLintIssue]:
+        return [issue for issue in self.issues if issue.level == "WARN"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def health_card_seed() -> dict:
+    return {
+        "version": 1,
+        "kind": "business-map",
+        "description": "Business concept map layered on top of graph-main facts.",
+        "concepts": [
+            {
+                "id": "health_card",
+                "name": "健康卡",
+                "aliases": ["healthCard", "health card", "健康权益卡", "健康卡运营", "健康卡商品"],
+                "status": "partial",
+                "summary": (
+                    "当前已探索运营端配置和 C 端商品透出。落地页、购买、退卡、权益、商品推荐等链路仍待补充。"
+                ),
+                "scenarios": [
+                    {
+                        "id": "health_card.admin_config",
+                        "name": "运营端配置",
+                        "status": "verified",
+                        "summary": "运营前端通过健康卡 REST 接口进入后端 controller，承载配置创建、查询等管理能力。",
+                        "anchors": [
+                            {
+                                "kind": "page",
+                                "ref": "ehealth-member",
+                                "role": "运营前端入口",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "rest_api",
+                                "ref": "/shopping/healthCard/createHealthCard",
+                                "role": "创建健康卡 REST 接口",
+                                "confidence": "verified",
+                            },
+                        ],
+                        "trace_hints": [
+                            {
+                                "from": "ehealth-member",
+                                "api": "/shopping/healthCard/createHealthCard",
+                                "max_depth": 8,
+                            }
+                        ],
+                        "gaps": [],
+                    },
+                    {
+                        "id": "health_card.goods_exposure",
+                        "name": "C端商品透出",
+                        "status": "verified",
+                        "summary": (
+                            "店铺页和商详页经 Venus 商品 MTop/HSF 进入商品资源聚合，再向 SummaryX 和 health-client 扩展。"
+                        ),
+                        "anchors": [
+                            {"kind": "page", "ref": "shop", "role": "店铺页入口", "confidence": "verified"},
+                            {"kind": "page", "ref": "ugoodsinfo", "role": "商详页入口", "confidence": "verified"},
+                            {
+                                "kind": "mtop_api",
+                                "ref": "mtop.venus.ShopCategoryService.getCategoryDetail",
+                                "role": "店铺分类/商品列表入口",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "mtop_api",
+                                "ref": "mtop.venus.ShopGoodsService.getShopGoodsResource",
+                                "role": "商详商品资源入口",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "mtop_api",
+                                "ref": "mtop.venus.ShopGoodsService.getShopGoodsDetail",
+                                "role": "商详商品详情入口",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "hsf_method",
+                                "ref": "me.ele.newretail.venus.client.api.ShopGoodsService#getShopGoodsResource",
+                                "role": "Venus 商品资源聚合方法",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "hsf_method",
+                                "ref": "me.ele.newretail.summaryx.newsdk.sdk.ItemServiceSummaryXClient#itemRendering",
+                                "role": "SummaryX 商品渲染方法",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "hsf_method",
+                                "ref": "me.ele.newretail.health.client.HealthMedicareTagQueryClient#matchMedicareTag",
+                                "role": "health-client 医保标签补全",
+                                "confidence": "verified",
+                            },
+                            {
+                                "kind": "hsf_method",
+                                "ref": "me.ele.newretail.health.client.HealthRxComplianceQueryClient#queryRxCompliance",
+                                "role": "health-client 处方/合规信息补全",
+                                "confidence": "verified",
+                            },
+                        ],
+                        "trace_hints": [
+                            {
+                                "from": "shop",
+                                "api": "mtop.venus.ShopCategoryService.getCategoryDetail",
+                                "max_depth": 10,
+                            },
+                            {
+                                "from": "ugoodsinfo",
+                                "api": "mtop.venus.ShopGoodsService.getShopGoodsResource",
+                                "max_depth": 10,
+                            },
+                            {
+                                "from": "ugoodsinfo",
+                                "api": "mtop.venus.ShopGoodsService.getShopGoodsDetail",
+                                "max_depth": 10,
+                            },
+                        ],
+                        "gaps": [
+                            "健康卡商品筛选条件、推荐策略和落地页承接关系仍需继续探索。",
+                        ],
+                    },
+                    {
+                        "id": "health_card.landing_page",
+                        "name": "落地页",
+                        "status": "unexplored",
+                        "summary": "待探索健康卡落地页入口、前端组件、MTop/REST 和后端承接链路。",
+                        "anchors": [],
+                        "trace_hints": [],
+                        "gaps": ["缺少入口 repo、页面和 API 锚点。"],
+                    },
+                    {
+                        "id": "health_card.purchase",
+                        "name": "购买",
+                        "status": "unexplored",
+                        "summary": "待探索健康卡购买、交易、权益发放和订单链路。",
+                        "anchors": [],
+                        "trace_hints": [],
+                        "gaps": ["缺少交易和权益发放相关锚点。"],
+                    },
+                    {
+                        "id": "health_card.refund",
+                        "name": "退卡",
+                        "status": "unexplored",
+                        "summary": "待探索退卡、退款、售后和权益回收链路。",
+                        "anchors": [],
+                        "trace_hints": [],
+                        "gaps": ["缺少售后/退款相关锚点。"],
+                    },
+                    {
+                        "id": "health_card.benefits",
+                        "name": "权益",
+                        "status": "unexplored",
+                        "summary": "待探索健康卡权益查询、展示、核销和履约链路。",
+                        "anchors": [],
+                        "trace_hints": [],
+                        "gaps": ["缺少权益服务和履约相关锚点。"],
+                    },
+                    {
+                        "id": "health_card.recommendation",
+                        "name": "商品推荐",
+                        "status": "unexplored",
+                        "summary": "待探索健康卡商品推荐、召回、排序和健康商品规则链路。",
+                        "anchors": [],
+                        "trace_hints": [],
+                        "gaps": ["缺少推荐入口和召回服务锚点。"],
+                    },
+                ],
+            }
+        ],
+    }
+
+
+def load_business_map(path: Path) -> dict:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"business map must be a JSON object: {path}")
+    data.setdefault("concepts", [])
+    return data
+
+
+def write_business_map(data: dict, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def is_kg_banks_root(path: Path) -> bool:
+    """Return True only for a marked kg-banks root, not any directory with that name."""
+    path = Path(path)
+    if path.name != _KG_BANKS_DIR_NAME:
+        return False
+    return (path / _KG_BANKS_ROOT_MARKER).exists() or (path / "graphify-out" / "business-map.json").is_file()
+
+
+def find_kg_banks_root(start: Path | None = None) -> Path | None:
+    """Find the marked kg-banks root from kg-banks itself or from its parent."""
+    start_path = Path.cwd() if start is None else Path(start)
+    start_path = start_path.resolve()
+    search_paths = [start_path, *start_path.parents]
+    for base in search_paths:
+        if is_kg_banks_root(base):
+            return base
+        child = base / _KG_BANKS_DIR_NAME
+        if child.is_dir() and is_kg_banks_root(child):
+            return child
+    return None
+
+
+def default_business_map_path(start: Path | None = None) -> Path:
+    root = find_kg_banks_root(start)
+    if root is not None:
+        return root / "graphify-out" / "business-map.json"
+    return Path("graphify-out") / "business-map.json"
+
+
+def _business_map_graph_ref(data: dict) -> str:
+    graph_meta = data.get("graph")
+    if isinstance(graph_meta, dict):
+        for key in ("path", "file", "graph_path"):
+            value = graph_meta.get(key)
+            if value:
+                return str(value)
+    for key in ("graph_path", "graph_file"):
+        value = data.get(key)
+        if value:
+            return str(value)
+    if isinstance(graph_meta, str):
+        return graph_meta
+    return ""
+
+
+def resolve_bound_graph_path(map_path: Path, graph_ref: str) -> Path:
+    raw = Path(graph_ref).expanduser()
+    if raw.is_absolute():
+        return raw
+    map_path = Path(map_path)
+    candidates = [
+        Path.cwd() / raw,
+        map_path.parent / raw,
+        map_path.parent.parent / raw,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[1]
+
+
+def default_business_graph_path(map_path: Path, start: Path | None = None) -> Path | None:
+    if Path(map_path).exists():
+        graph_ref = _business_map_graph_ref(load_business_map(Path(map_path)))
+        if graph_ref:
+            return resolve_bound_graph_path(Path(map_path), graph_ref)
+
+    root = find_kg_banks_root(start)
+    graphify_out = (root / "graphify-out") if root is not None else Path("graphify-out")
+    candidates = sorted(
+        p for p in graphify_out.glob("graph*.json")
+        if p.name != "business-map.json"
+    )
+    if not candidates:
+        fallback = graphify_out / "graph-main-merged.json"
+        return fallback if fallback.exists() else None
+    for candidate in candidates:
+        if candidate.name == "graph-main-merged.json":
+            return candidate
+    return candidates[0]
+
+
+def init_business_map(concept: str, out_path: Path, *, force: bool = False) -> dict:
+    if out_path.exists() and not force:
+        raise FileExistsError(f"business map already exists: {out_path}")
+    if not _matches_text(concept, "健康卡", ["health_card", "healthCard", "health card"]):
+        raise ValueError(f"unsupported seed concept: {concept}. Currently supported: 健康卡")
+    data = health_card_seed()
+    write_business_map(data, out_path)
+    return data
+
+
+def _norm(v: object) -> str:
+    return str(v or "").strip().lower()
+
+
+def _compact_ws(v: object) -> str:
+    return re.sub(r"\s+", " ", str(v or "").strip())
+
+
+def _ascii_terms(text: str) -> list[str]:
+    pieces: list[str] = []
+    for raw in re.findall(r"[A-Za-z0-9_./#:-]+", text):
+        raw = raw.replace("_", " ").replace("/", " ").replace(":", " ")
+        raw = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", raw)
+        pieces.extend(part.lower() for part in re.split(r"[^A-Za-z0-9#.-]+", raw) if part)
+    return pieces
+
+
+def _cjk_terms(text: str) -> list[str]:
+    terms: list[str] = []
+    for block in re.findall(r"[\u4e00-\u9fff]+", text):
+        terms.extend(ch for ch in block if ch.strip())
+        terms.extend(block[i : i + 2] for i in range(max(0, len(block) - 1)))
+    return terms
+
+
+def _query_terms(text: str) -> set[str]:
+    stop = {"相关", "链路", "流程", "场景", "查询", "查看", "一下", "怎么", "如何"}
+    terms = set(_ascii_terms(text) + _cjk_terms(text))
+    return {term for term in terms if term and term not in stop}
+
+
+def _matches_text(query: str, name: str, aliases: list[str] | None = None) -> bool:
+    q = _norm(query)
+    values = [_norm(name), *[_norm(a) for a in aliases or []]]
+    return any(q == v or (q and q in v) or (v and v in q) for v in values)
+
+
+def _concept_matches(concept: dict, query: str) -> bool:
+    return _matches_text(query, str(concept.get("name", "")), [str(concept.get("id", "")), *concept.get("aliases", [])])
+
+
+def _scenario_matches(scenario: dict, query: str) -> bool:
+    return _matches_text(query, str(scenario.get("name", "")), [str(scenario.get("id", ""))])
+
+
+def find_concept(data: dict, query: str) -> dict:
+    matches = [c for c in data.get("concepts", []) if isinstance(c, dict) and _concept_matches(c, query)]
+    if not matches:
+        raise ValueError(f"no business concept matched: {query}")
+    return sorted(matches, key=lambda c: _STATUS_ORDER.get(str(c.get("status", "")), 99))[0]
+
+
+def find_scenarios(concept: dict, query: str = "") -> list[dict]:
+    scenarios = [s for s in concept.get("scenarios", []) if isinstance(s, dict)]
+    if not query:
+        return sorted(scenarios, key=lambda s: (_STATUS_ORDER.get(str(s.get("status", "")), 99), str(s.get("id", ""))))
+    matches = [s for s in scenarios if _scenario_matches(s, query)]
+    if not matches:
+        raise ValueError(f"no scenario matched '{query}' in concept {concept.get('name', concept.get('id'))}")
+    return sorted(matches, key=lambda s: (_STATUS_ORDER.get(str(s.get("status", "")), 99), str(s.get("id", ""))))
+
+
+def _flow_matches(flow: dict, query: str) -> bool:
+    return _matches_text(query, str(flow.get("name", "")), [str(flow.get("id", ""))])
+
+
+def find_flow(scenario: dict, query: str = "") -> dict | None:
+    if not query:
+        return None
+    matches = [flow for flow in _scenario_flows(scenario) if _flow_matches(flow, query)]
+    if not matches:
+        raise ValueError(f"no flow matched '{query}' in scenario {scenario.get('name', scenario.get('id'))}")
+    return sorted(matches, key=lambda f: (_STATUS_ORDER.get(str(f.get("status", "")), 99), str(f.get("id", ""))))[0]
+
+
+def _scenario_flows(scenario: dict) -> list[dict]:
+    return [flow for flow in scenario.get("flows", []) if isinstance(flow, dict)]
+
+
+def _format_business_path(concept: dict, scenario: dict | None = None, flow: dict | None = None) -> str:
+    parts = [str(concept.get("id", concept.get("name", "<concept>")))]
+    if scenario is not None:
+        parts.append(str(scenario.get("id", scenario.get("name", "<scenario>"))))
+    if flow is not None:
+        parts.append(str(flow.get("id", flow.get("name", "<flow>"))))
+    return " / ".join(parts)
+
+
+def _scenario_anchors(scenario: dict) -> list[tuple[dict, str]]:
+    items: list[tuple[dict, str]] = []
+    for anchor in scenario.get("anchors", []):
+        if isinstance(anchor, dict):
+            items.append((anchor, ""))
+    for flow in _scenario_flows(scenario):
+        flow_id = str(flow.get("id", flow.get("name", "")))
+        for anchor in flow.get("anchors", []):
+            if isinstance(anchor, dict):
+                items.append((anchor, flow_id))
+    return items
+
+
+def _scenario_trace_hints(scenario: dict) -> list[tuple[dict, str]]:
+    items: list[tuple[dict, str]] = []
+    for hint in scenario.get("trace_hints", []):
+        if isinstance(hint, dict):
+            items.append((hint, ""))
+    for flow in _scenario_flows(scenario):
+        flow_id = str(flow.get("id", flow.get("name", "")))
+        for hint in flow.get("trace_hints", []):
+            if isinstance(hint, dict):
+                items.append((hint, flow_id))
+    return items
+
+
+def _list_constraint_values(value: object) -> list[str]:
+    if isinstance(value, str):
+        return [item.strip() for item in value.split(",") if item.strip()]
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []
+
+
+def _merge_search_constraints(*owners: dict) -> dict:
+    merged = {"prefer_repos": [], "exclude_repos": []}
+    for owner in owners:
+        constraints = owner.get("search_constraints", {}) if isinstance(owner, dict) else {}
+        if not isinstance(constraints, dict):
+            continue
+        for key in ("prefer_repos", "exclude_repos"):
+            for item in _list_constraint_values(constraints.get(key)):
+                if item not in merged[key]:
+                    merged[key].append(item)
+    return merged
+
+
+def _scenario_trace_items(scenario: dict, flow_query: str = "") -> list[tuple[dict, str, dict]]:
+    items: list[tuple[dict, str, dict]] = []
+    scenario_constraints = _merge_search_constraints(scenario)
+    if not flow_query:
+        for hint in scenario.get("trace_hints", []):
+            if isinstance(hint, dict):
+                items.append((hint, "", _merge_search_constraints({"search_constraints": scenario_constraints}, hint)))
+    for flow in _scenario_flows(scenario):
+        flow_id = str(flow.get("id", flow.get("name", "")))
+        if flow_query and not _flow_matches(flow, flow_query):
+            continue
+        flow_constraints = _merge_search_constraints(scenario, flow)
+        for hint in flow.get("trace_hints", []):
+            if isinstance(hint, dict):
+                items.append((hint, flow_id, _merge_search_constraints({"search_constraints": flow_constraints}, hint)))
+    return items
+
+
+def _scenario_gaps(scenario: dict) -> list[str]:
+    gaps = [str(g) for g in scenario.get("gaps", []) if g]
+    for flow in _scenario_flows(scenario):
+        flow_name = str(flow.get("name", flow.get("id", "")))
+        for gap in flow.get("gaps", []):
+            if gap:
+                gaps.append(f"{flow_name}: {gap}" if flow_name else str(gap))
+    return gaps
+
+
+def _format_accepted_gap(gap: object) -> str:
+    if isinstance(gap, dict):
+        parts = []
+        gap_id = str(gap.get("id", "")).strip()
+        gap_type = str(gap.get("type", "")).strip()
+        status = str(gap.get("status", "")).strip()
+        summary = str(gap.get("summary", "")).strip()
+        if gap_id:
+            parts.append(gap_id)
+        if gap_type:
+            parts.append(f"type={gap_type}")
+        if status:
+            parts.append(f"status={status}")
+        if summary:
+            parts.append(summary)
+        return " ".join(parts)
+    return str(gap)
+
+
+def _accepted_gap_summary(gap: object) -> str:
+    if isinstance(gap, dict):
+        return str(gap.get("summary", ""))
+    return str(gap)
+
+
+def _append_anchor_text(parts: list[str], anchors: list[dict]) -> None:
+    for anchor in anchors:
+        if not isinstance(anchor, dict):
+            continue
+        parts.extend(
+            [
+                str(anchor.get("kind", "")),
+                str(anchor.get("ref", "")),
+                str(anchor.get("role", "")),
+                str(anchor.get("confidence", "")),
+            ]
+        )
+
+
+def _append_trace_hint_text(parts: list[str], hints: list[dict]) -> None:
+    for hint in hints:
+        if not isinstance(hint, dict):
+            continue
+        parts.extend([str(hint.get("from", "")), str(hint.get("api", ""))])
+
+
+def _append_gap_text(parts: list[str], owner: dict) -> None:
+    for gap in owner.get("gaps", []):
+        parts.append(str(gap))
+    for gap in owner.get("accepted_gaps", []):
+        if isinstance(gap, dict):
+            parts.extend([str(gap.get("summary", "")), str(gap.get("reason", "")), str(gap.get("stop_rule", ""))])
+        else:
+            parts.append(str(gap))
+
+
+def _constraints_text(owner: dict) -> list[str]:
+    constraints = _merge_search_constraints(owner)
+    return [*constraints["prefer_repos"], *constraints["exclude_repos"]]
+
+
+def _business_query_docs(data: dict) -> list[dict]:
+    docs: list[dict] = []
+    for concept in data.get("concepts", []):
+        if not isinstance(concept, dict):
+            continue
+        concept_parts = [
+            str(concept.get("id", "")),
+            str(concept.get("name", "")),
+            *[str(a) for a in concept.get("aliases", [])],
+            str(concept.get("summary", "")),
+            str(concept.get("status", "")),
+        ]
+        concept_text = " ".join(_compact_ws(part) for part in concept_parts if _compact_ws(part))
+        docs.append(
+            {
+                "type": "concept",
+                "concept": concept,
+                "scenario": None,
+                "flow": None,
+                "path": str(concept.get("id", concept.get("name", ""))),
+                "text": concept_text,
+                "primary": " ".join(str(v) for v in [concept.get("id", ""), concept.get("name", ""), *concept.get("aliases", [])]),
+                "status": str(concept.get("status", "")),
+            }
+        )
+        for scenario in concept.get("scenarios", []):
+            if not isinstance(scenario, dict):
+                continue
+            scenario_parts = [
+                concept_text,
+                str(scenario.get("id", "")),
+                str(scenario.get("name", "")),
+                str(scenario.get("status", "")),
+                str(scenario.get("summary", "")),
+                str(scenario.get("verification_scope", "")),
+                *_constraints_text(scenario),
+            ]
+            _append_anchor_text(scenario_parts, [a for a, flow_id in _scenario_anchors(scenario) if not flow_id])
+            _append_trace_hint_text(scenario_parts, [h for h, flow_id in _scenario_trace_hints(scenario) if not flow_id])
+            _append_gap_text(scenario_parts, scenario)
+            docs.append(
+                {
+                    "type": "scenario",
+                    "concept": concept,
+                    "scenario": scenario,
+                    "flow": None,
+                    "path": f"{concept.get('id', concept.get('name', ''))}/{scenario.get('id', scenario.get('name', ''))}",
+                    "text": " ".join(_compact_ws(part) for part in scenario_parts if _compact_ws(part)),
+                    "primary": " ".join(str(v) for v in [scenario.get("id", ""), scenario.get("name", "")]),
+                    "status": str(scenario.get("status", "")),
+                }
+            )
+            for flow in _scenario_flows(scenario):
+                flow_parts = [
+                    concept_text,
+                    str(scenario.get("id", "")),
+                    str(scenario.get("name", "")),
+                    str(scenario.get("summary", "")),
+                    str(flow.get("id", "")),
+                    str(flow.get("name", "")),
+                    str(flow.get("status", scenario.get("status", ""))),
+                    str(flow.get("summary", "")),
+                    str(flow.get("verification_scope", "")),
+                    *_constraints_text(scenario),
+                    *_constraints_text(flow),
+                ]
+                _append_anchor_text(flow_parts, [a for a in flow.get("anchors", []) if isinstance(a, dict)])
+                _append_trace_hint_text(flow_parts, [h for h in flow.get("trace_hints", []) if isinstance(h, dict)])
+                _append_gap_text(flow_parts, flow)
+                docs.append(
+                    {
+                        "type": "flow",
+                        "concept": concept,
+                        "scenario": scenario,
+                        "flow": flow,
+                        "path": (
+                            f"{concept.get('id', concept.get('name', ''))}/"
+                            f"{scenario.get('id', scenario.get('name', ''))}/"
+                            f"{flow.get('id', flow.get('name', ''))}"
+                        ),
+                        "text": " ".join(_compact_ws(part) for part in flow_parts if _compact_ws(part)),
+                        "primary": " ".join(str(v) for v in [flow.get("id", ""), flow.get("name", "")]),
+                        "status": str(flow.get("status", scenario.get("status", ""))),
+                    }
+                )
+    return docs
+
+
+def _score_business_doc(query: str, doc: dict) -> tuple[int, list[str]]:
+    q = _norm(query)
+    text = _norm(doc.get("text", ""))
+    primary = _norm(doc.get("primary", ""))
+    q_terms = _query_terms(query)
+    text_terms = _query_terms(str(doc.get("text", "")))
+    primary_terms = _query_terms(str(doc.get("primary", "")))
+    hits = sorted(q_terms & text_terms)
+    score = 0
+    reasons: list[str] = []
+    if q and (q == primary or q in primary or primary in q):
+        score += 120
+        reasons.append("primary")
+    if q and q in text:
+        score += 80
+        reasons.append("phrase")
+    primary_hits = q_terms & primary_terms
+    if primary_hits:
+        score += 25 * len(primary_hits)
+        reasons.append("primary_terms:" + ",".join(sorted(primary_hits)[:8]))
+    if hits:
+        score += min(90, 8 * len(hits))
+        reasons.append("terms:" + ",".join(hits[:10]))
+    if not reasons:
+        return 0, []
+    if doc.get("type") == "flow":
+        score += 8
+    elif doc.get("type") == "scenario":
+        score += 4
+    status = str(doc.get("status", ""))
+    if status == "verified":
+        score += 5
+    elif status == "candidate":
+        score += 2
+    return score, reasons
+
+
+def _summarize_business_doc(doc: dict, score: int, reasons: list[str]) -> dict:
+    concept = doc.get("concept") or {}
+    scenario = doc.get("scenario") or {}
+    flow = doc.get("flow") or {}
+    summary_owner = flow if flow else scenario if scenario else concept
+    trace_hints: list[dict] = []
+    if flow:
+        trace_hints = [h for h in flow.get("trace_hints", []) if isinstance(h, dict)]
+    elif scenario:
+        trace_hints = [h for h, _flow_id in _scenario_trace_hints(scenario)]
+    constraints = _merge_search_constraints(scenario, flow)
+    return {
+        "type": doc.get("type"),
+        "score": score,
+        "reasons": reasons,
+        "concept": concept.get("id") or concept.get("name"),
+        "concept_name": concept.get("name"),
+        "scenario": scenario.get("id") or scenario.get("name") if scenario else None,
+        "scenario_name": scenario.get("name") if scenario else None,
+        "flow": flow.get("id") or flow.get("name") if flow else None,
+        "flow_name": flow.get("name") if flow else None,
+        "status": summary_owner.get("status", doc.get("status", "")),
+        "summary": summary_owner.get("summary", ""),
+        "verification_scope": summary_owner.get("verification_scope", ""),
+        "gaps": _compact_gap_items([g for g in summary_owner.get("gaps", []) if g]),
+        "accepted_gaps": _compact_gap_items([g for g in summary_owner.get("accepted_gaps", []) if g]),
+        "trace_hint_count": len(trace_hints),
+        "search_constraints": constraints,
+    }
+
+
+def _compact_gap_items(items: list[object], *, limit: int = 3) -> list[str]:
+    compact: list[str] = []
+    for item in items:
+        if isinstance(item, dict):
+            text = str(item.get("summary") or item.get("reason") or item.get("id") or "").strip()
+        else:
+            text = str(item or "").strip()
+        if text:
+            compact.append(text)
+        if len(compact) >= limit:
+            break
+    return compact
+
+
+def _business_context(data: dict, query: str, *, limit: int = 4) -> list[dict]:
+    query_terms = _query_terms(query)
+    contexts: list[tuple[int, dict]] = []
+    for concept in data.get("concepts", []):
+        if not isinstance(concept, dict):
+            continue
+        concept_terms = _query_terms(
+            " ".join(
+                [
+                    str(concept.get("id", "")),
+                    str(concept.get("name", "")),
+                    *[str(a) for a in concept.get("aliases", [])],
+                    str(concept.get("summary", "")),
+                ]
+            )
+        )
+        concept_score = len(query_terms & concept_terms)
+        scenarios: list[dict] = []
+        for scenario in concept.get("scenarios", []):
+            if not isinstance(scenario, dict):
+                continue
+            scenario_terms = _query_terms(
+                " ".join(
+                    [
+                        str(scenario.get("id", "")),
+                        str(scenario.get("name", "")),
+                        str(scenario.get("summary", "")),
+                        str(scenario.get("verification_scope", "")),
+                        *[str(a.get("ref", "")) + " " + str(a.get("role", "")) for a, _flow in _scenario_anchors(scenario) if isinstance(a, dict)],
+                    ]
+                )
+            )
+            scenario_score = len(query_terms & scenario_terms)
+            constraints = _merge_search_constraints(scenario)
+            scenarios.append(
+                {
+                    "id": scenario.get("id"),
+                    "name": scenario.get("name"),
+                    "status": scenario.get("status"),
+                    "score_hint": scenario_score,
+                    "summary": scenario.get("summary", ""),
+                    "search_constraints": constraints,
+                    "gaps": _compact_gap_items([g for g in scenario.get("gaps", []) if g]),
+                    "accepted_gaps": _compact_gap_items([g for g in scenario.get("accepted_gaps", []) if g]),
+                }
+            )
+            concept_score = max(concept_score, scenario_score)
+        scenarios.sort(key=lambda item: (int(item.get("score_hint", 0)), -_STATUS_ORDER.get(str(item.get("status", "")), 99), str(item.get("id", ""))), reverse=True)
+        contexts.append(
+            (
+                concept_score,
+                {
+                    "concept": concept.get("id") or concept.get("name"),
+                    "name": concept.get("name"),
+                    "status": concept.get("status"),
+                    "summary": concept.get("summary", ""),
+                    "aliases": concept.get("aliases", []),
+                    "top_scenarios": scenarios[:limit],
+                },
+            )
+        )
+    contexts.sort(key=lambda item: (item[0], str(item[1].get("concept", ""))), reverse=True)
+    return [context for _score, context in contexts[:limit]]
+
+
+def match_business_query(data: dict, query: str, *, top_k: int = 5) -> dict:
+    scored: list[tuple[int, dict, list[str]]] = []
+    for doc in _business_query_docs(data):
+        score, reasons = _score_business_doc(query, doc)
+        if score > 0:
+            scored.append((score, doc, reasons))
+    scored.sort(
+        key=lambda item: (
+            item[0],
+            2 if item[1].get("type") == "flow" else 1 if item[1].get("type") == "scenario" else 0,
+            -_STATUS_ORDER.get(str(item[1].get("status", "")), 99),
+            str(item[1].get("path", "")),
+        ),
+        reverse=True,
+    )
+    top_matches = [_summarize_business_doc(doc, score, reasons) for score, doc, reasons in scored[:top_k]]
+    specific_matches = [c for c in top_matches if c.get("type") in {"scenario", "flow"}]
+    best = specific_matches[0] if specific_matches else top_matches[0] if top_matches else None
+    if best:
+        top_matches = [best, *[match for match in top_matches if match is not best]]
+    return {
+        "status": "matched" if best else "none",
+        "scope": best.get("type") if best else None,
+        "best": best,
+        "top_matches": top_matches,
+    }
+
+
+def _load_graph_nodes(graph_path: Path) -> list[dict]:
+    data = json.loads(graph_path.read_text(encoding="utf-8"))
+    return [n for n in data.get("nodes", []) if isinstance(n, dict)]
+
+
+def search_graph_main_matches(graph_path: Path, query: str, *, top_k: int = 10) -> list[dict]:
+    preferred_kinds = {"page", "component", "mtop_api", "rest_api", "hsf_method"}
+    q = _norm(query)
+    q_terms = _query_terms(query)
+    results: list[tuple[int, dict, list[str]]] = []
+    for node in _load_graph_nodes(graph_path):
+        text_parts = [
+            str(node.get("id", "")),
+            str(node.get("label", "")),
+            str(node.get("canonical_key", "")),
+            str(node.get("repo", "")),
+            str(node.get("source_file", "")),
+            str(node.get("main_kind", "")),
+        ]
+        text = _norm(" ".join(text_parts))
+        terms = _query_terms(" ".join(text_parts))
+        hits = sorted(q_terms & terms)
+        score = 0
+        reasons: list[str] = []
+        if q and q in text:
+            score += 80
+            reasons.append("phrase")
+        if hits:
+            score += min(80, 8 * len(hits))
+            reasons.append("terms:" + ",".join(hits[:8]))
+        if str(node.get("main_kind", "")) in preferred_kinds:
+            score += 10
+        if not score:
+            continue
+        results.append((score, node, reasons))
+    results.sort(key=lambda item: (item[0], str(item[1].get("main_kind", "")) in preferred_kinds, str(item[1].get("label", ""))), reverse=True)
+    return [
+        {
+            "score": score,
+            "reasons": reasons,
+            "id": node.get("id"),
+            "label": node.get("label"),
+            "kind": node.get("main_kind"),
+            "repo": node.get("repo"),
+            "canonical_key": node.get("canonical_key"),
+            "source_file": node.get("source_file"),
+            "source_location": node.get("source_location"),
+        }
+        for score, node, reasons in results[:top_k]
+    ]
+
+
+def _node_values(node: dict) -> set[str]:
+    vals = {
+        _norm(node.get("id")),
+        _norm(node.get("label")),
+        _norm(node.get("canonical_key")),
+        _norm(node.get("local_id")),
+        _norm(node.get("repo")),
+        _norm(node.get("source_file")),
+    }
+    return {v for v in vals if v}
+
+
+def _load_graph_nodes(path: Path) -> list[dict]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return list(data.get("nodes", []))
+
+
+def _matches_graph_ref(node: dict, ref: object) -> bool:
+    q = _norm(ref)
+    if not q:
+        return False
+    if q.startswith("/"):
+        q_values = {q, f"rest_api:{q}"}
+    elif q.startswith(("mtop_api:", "rest_api:", "hsf_method:", "hsf_api:", "dependency_method:", "dependency:")):
+        q_values = {q}
+    elif str(ref).startswith("mtop."):
+        q_values = {q, f"mtop_api:{q}"}
+    else:
+        q_values = {q}
+    vals = _node_values(node)
+    return any(qv == v or qv in v for qv in q_values for v in vals)
+
+
+def validate_business_map(map_path: Path, graph_path: Path) -> BusinessValidationResult:
+    data = load_business_map(map_path)
+    nodes = _load_graph_nodes(graph_path)
+    missing_anchors: list[dict] = []
+    missing_trace_refs: list[dict] = []
+    concept_count = 0
+    scenario_count = 0
+    anchor_count = 0
+    trace_hint_count = 0
+
+    def exists(ref: object) -> bool:
+        return any(_matches_graph_ref(node, ref) for node in nodes)
+
+    for concept in data.get("concepts", []):
+        if not isinstance(concept, dict):
+            continue
+        concept_count += 1
+        for scenario in concept.get("scenarios", []):
+            if not isinstance(scenario, dict):
+                continue
+            scenario_count += 1
+            scenario_id = str(scenario.get("id", ""))
+            for anchor, flow_id in _scenario_anchors(scenario):
+                anchor_count += 1
+                ref = anchor.get("ref", "")
+                if not exists(ref):
+                    missing_anchors.append(
+                        {
+                            "concept": concept.get("id", ""),
+                            "scenario": scenario_id,
+                            "flow": flow_id,
+                            "kind": anchor.get("kind", ""),
+                            "ref": ref,
+                            "role": anchor.get("role", ""),
+                        }
+                    )
+            for hint, flow_id in _scenario_trace_hints(scenario):
+                trace_hint_count += 1
+                for key in ("from", "api"):
+                    ref = hint.get(key, "")
+                    if ref and not exists(ref):
+                        missing_trace_refs.append(
+                            {
+                                "concept": concept.get("id", ""),
+                                "scenario": scenario_id,
+                                "flow": flow_id,
+                                "field": key,
+                                "ref": ref,
+                            }
+                        )
+
+    return BusinessValidationResult(
+        concept_count=concept_count,
+        scenario_count=scenario_count,
+        anchor_count=anchor_count,
+        trace_hint_count=trace_hint_count,
+        missing_anchors=missing_anchors,
+        missing_trace_refs=missing_trace_refs,
+    )
+
+
+def lint_business_map(map_path: Path) -> BusinessLintResult:
+    data = load_business_map(map_path)
+    issues: list[BusinessLintIssue] = []
+
+    def add(level: str, path: str, message: str) -> None:
+        issues.append(BusinessLintIssue(level=level, path=path, message=message))
+
+    def check_anchors(owner: dict, path: str) -> None:
+        seen: set[tuple[str, str]] = set()
+        for idx, anchor in enumerate(owner.get("anchors", [])):
+            anchor_path = f"{path}.anchors[{idx}]"
+            if not isinstance(anchor, dict):
+                add("ERROR", anchor_path, "anchor must be an object")
+                continue
+            for key in ("kind", "ref", "role", "confidence"):
+                if not str(anchor.get(key, "")).strip():
+                    add("ERROR", anchor_path, f"anchor missing required field: {key}")
+            confidence = str(anchor.get("confidence", "")).strip()
+            if confidence and confidence not in {"verified", "candidate", "inferred", "stale"}:
+                add("ERROR", anchor_path, f"anchor confidence is not allowed: {confidence}")
+            identity = (str(anchor.get("kind", "")).strip(), str(anchor.get("ref", "")).strip())
+            if identity in seen:
+                add("WARN", anchor_path, f"duplicate anchor: {identity[0]} {identity[1]}")
+            seen.add(identity)
+
+    def check_trace_hints(owner: dict, path: str) -> None:
+        for idx, hint in enumerate(owner.get("trace_hints", [])):
+            hint_path = f"{path}.trace_hints[{idx}]"
+            if not isinstance(hint, dict):
+                add("ERROR", hint_path, "trace_hint must be an object")
+                continue
+            if not str(hint.get("from", "")).strip():
+                add("ERROR", hint_path, "trace_hint missing required field: from")
+            depth = hint.get("max_depth", 8)
+            if not isinstance(depth, int) or depth <= 0:
+                add("ERROR", hint_path, "trace_hint max_depth must be a positive integer")
+
+    def check_search_constraints(owner: dict, path: str) -> None:
+        constraints = owner.get("search_constraints")
+        if constraints is None:
+            return
+        if not isinstance(constraints, dict):
+            add("ERROR", f"{path}.search_constraints", "search_constraints must be an object")
+            return
+        for key in ("prefer_repos", "exclude_repos"):
+            if key in constraints and not isinstance(constraints.get(key), list):
+                add("ERROR", f"{path}.search_constraints.{key}", f"{key} must be a list")
+            for idx, value in enumerate(constraints.get(key, []) if isinstance(constraints.get(key), list) else []):
+                if not str(value).strip():
+                    add("ERROR", f"{path}.search_constraints.{key}[{idx}]", f"{key} entries must be non-empty strings")
+
+    def check_accepted_gaps(owner: dict, path: str) -> None:
+        accepted = owner.get("accepted_gaps", [])
+        if accepted and not isinstance(accepted, list):
+            add("ERROR", f"{path}.accepted_gaps", "accepted_gaps must be a list")
+            return
+        active_gap_text = "\n".join(str(g) for g in owner.get("gaps", []) if g)
+        for idx, gap in enumerate(accepted):
+            gap_path = f"{path}.accepted_gaps[{idx}]"
+            if not isinstance(gap, dict):
+                add("ERROR", gap_path, "accepted_gap must be an object")
+                continue
+            for key in ("id", "type", "status", "summary", "reason", "stop_rule"):
+                if not str(gap.get(key, "")).strip():
+                    add("ERROR", gap_path, f"accepted_gap missing required field: {key}")
+            if str(gap.get("type", "")).strip() == "accepted_boundary" and not str(gap.get("stop_rule", "")).strip():
+                add("ERROR", gap_path, "accepted_boundary must define stop_rule")
+            summary = _accepted_gap_summary(gap).strip()
+            if summary and summary in active_gap_text:
+                add("ERROR", gap_path, "accepted gap is duplicated in active gaps; keep it only in accepted_gaps")
+
+    def check_owner(owner: dict, path: str, *, require_scope_for_verified: bool) -> None:
+        status = str(owner.get("status", "")).strip()
+        if status and status not in _STATUS_ORDER:
+            add("ERROR", path, f"status is not allowed: {status}")
+        if status == "verified" and require_scope_for_verified and not str(owner.get("verification_scope", "")).strip():
+            add("WARN", path, "verified flow should declare verification_scope")
+        if status == "verified":
+            candidate_refs = [
+                str(anchor.get("ref", ""))
+                for anchor in owner.get("anchors", [])
+                if isinstance(anchor, dict) and str(anchor.get("confidence", "")).strip() == "candidate"
+            ]
+            if candidate_refs:
+                add("ERROR", path, "verified item has candidate anchors: " + ", ".join(candidate_refs))
+        if owner.get("accepted_gaps") and not str(owner.get("verification_scope", "")).strip():
+            add("ERROR", path, "accepted_gaps require verification_scope to define the boundary")
+        gaps = owner.get("gaps", [])
+        if gaps is not None and not isinstance(gaps, list):
+            add("ERROR", f"{path}.gaps", "gaps must be a list")
+        if status == "verified" and any(g for g in gaps if g):
+            add("WARN", path, "verified item has active gaps; use accepted_gaps for known boundaries")
+        check_anchors(owner, path)
+        check_trace_hints(owner, path)
+        check_search_constraints(owner, path)
+        check_accepted_gaps(owner, path)
+
+    if data.get("kind") != "business-map":
+        add("ERROR", "<root>", "kind must be business-map")
+    if "concepts" not in data or not isinstance(data.get("concepts"), list):
+        add("ERROR", "<root>.concepts", "concepts must be a list")
+        return BusinessLintResult(issues)
+
+    for concept_idx, concept in enumerate(data.get("concepts", [])):
+        concept_path = f"concepts[{concept_idx}]"
+        if not isinstance(concept, dict):
+            add("ERROR", concept_path, "concept must be an object")
+            continue
+        if not str(concept.get("id", "")).strip():
+            add("ERROR", concept_path, "concept missing required field: id")
+        if not str(concept.get("name", "")).strip():
+            add("ERROR", concept_path, "concept missing required field: name")
+        scenarios = concept.get("scenarios", [])
+        if not isinstance(scenarios, list):
+            add("ERROR", f"{concept_path}.scenarios", "scenarios must be a list")
+            continue
+        flow_names: dict[str, str] = {}
+        scenario_names: dict[str, str] = {}
+        for scenario_idx, scenario in enumerate(scenarios):
+            scenario_path = f"{concept_path}.scenarios[{scenario_idx}]"
+            if not isinstance(scenario, dict):
+                add("ERROR", scenario_path, "scenario must be an object")
+                continue
+            scenario_id = str(scenario.get("id", "")).strip()
+            scenario_name = str(scenario.get("name", "")).strip()
+            if not scenario_id:
+                add("ERROR", scenario_path, "scenario missing required field: id")
+            if not scenario_name:
+                add("ERROR", scenario_path, "scenario missing required field: name")
+            if scenario_name:
+                scenario_names[scenario_name] = _format_business_path(concept, scenario)
+            check_owner(scenario, scenario_path, require_scope_for_verified=False)
+            flows = scenario.get("flows", [])
+            if flows and not isinstance(flows, list):
+                add("ERROR", f"{scenario_path}.flows", "flows must be a list")
+                continue
+            for flow_idx, flow in enumerate(flows):
+                flow_path = f"{scenario_path}.flows[{flow_idx}]"
+                if not isinstance(flow, dict):
+                    add("ERROR", flow_path, "flow must be an object")
+                    continue
+                flow_id = str(flow.get("id", "")).strip()
+                flow_name = str(flow.get("name", "")).strip()
+                if not flow_id:
+                    add("ERROR", flow_path, "flow missing required field: id")
+                if not flow_name:
+                    add("ERROR", flow_path, "flow missing required field: name")
+                if flow_name:
+                    flow_names[flow_name] = _format_business_path(concept, scenario, flow)
+                check_owner(flow, flow_path, require_scope_for_verified=True)
+        for scenario_name, scenario_path in scenario_names.items():
+            flow_path = flow_names.get(scenario_name)
+            if flow_path:
+                add(
+                    "WARN",
+                    scenario_path,
+                    f"scenario name overlaps a flow ({flow_path}); document whether the scenario is a broader backlog or remove the duplicate",
+                )
+
+    return BusinessLintResult(issues)
+
+
+def format_business_show(data: dict, *, concept_query: str = "", scenario_query: str = "") -> str:
+    concepts = [find_concept(data, concept_query)] if concept_query else [
+        c for c in data.get("concepts", []) if isinstance(c, dict)
+    ]
+    lines: list[str] = []
+    for concept in concepts:
+        lines.append(f"Concept: {concept.get('name', concept.get('id', ''))} ({concept.get('id', '')})")
+        lines.append(f"Status: {concept.get('status', '')}")
+        aliases = concept.get("aliases", [])
+        if aliases:
+            lines.append(f"Aliases: {', '.join(str(a) for a in aliases)}")
+        if concept.get("summary"):
+            lines.append(f"Summary: {concept.get('summary')}")
+        lines.append("")
+        lines.append("Scenarios:")
+        for scenario in find_scenarios(concept, scenario_query):
+            lines.append(f"- {scenario.get('name', scenario.get('id', ''))} ({scenario.get('id', '')}) status={scenario.get('status', '')}")
+            if scenario.get("summary"):
+                lines.append(f"  summary: {scenario.get('summary')}")
+            if scenario.get("verification_scope"):
+                lines.append(f"  verification_scope: {scenario.get('verification_scope')}")
+            constraints = _merge_search_constraints(scenario)
+            if constraints["prefer_repos"] or constraints["exclude_repos"]:
+                lines.append(
+                    "  search_constraints: "
+                    f"prefer_repos={', '.join(constraints['prefer_repos']) or '-'} "
+                    f"exclude_repos={', '.join(constraints['exclude_repos']) or '-'}"
+                )
+            anchors = [a for a, flow_id in _scenario_anchors(scenario) if not flow_id]
+            if anchors:
+                lines.append("  anchors:")
+                for anchor in anchors:
+                    role = f" role={anchor.get('role', '')}" if anchor.get("role") else ""
+                    confidence = f" confidence={anchor.get('confidence', '')}" if anchor.get("confidence") else ""
+                    lines.append(f"  - {anchor.get('kind', '')}: {anchor.get('ref', '')}{role}{confidence}")
+            hints = [h for h, flow_id in _scenario_trace_hints(scenario) if not flow_id]
+            if hints:
+                lines.append("  trace_hints:")
+                for hint in hints:
+                    api = f" --api {hint.get('api')}" if hint.get("api") else ""
+                    lines.append(f"  - --from {hint.get('from', '')}{api} --max-depth {hint.get('max_depth', 8)}")
+            flows = _scenario_flows(scenario)
+            if flows:
+                lines.append("  flows:")
+                for flow in flows:
+                    lines.append(
+                        f"  - {flow.get('name', flow.get('id', ''))} ({flow.get('id', '')}) "
+                        f"status={flow.get('status', scenario.get('status', ''))}"
+                    )
+                    if flow.get("summary"):
+                        lines.append(f"    summary: {flow.get('summary')}")
+                    if flow.get("verification_scope"):
+                        lines.append(f"    verification_scope: {flow.get('verification_scope')}")
+                    flow_constraints = _merge_search_constraints(scenario, flow)
+                    if flow_constraints["prefer_repos"] or flow_constraints["exclude_repos"]:
+                        lines.append(
+                            "    search_constraints: "
+                            f"prefer_repos={', '.join(flow_constraints['prefer_repos']) or '-'} "
+                            f"exclude_repos={', '.join(flow_constraints['exclude_repos']) or '-'}"
+                        )
+                    flow_anchors = [a for a in flow.get("anchors", []) if isinstance(a, dict)]
+                    if flow_anchors:
+                        lines.append("    anchors:")
+                        for anchor in flow_anchors:
+                            role = f" role={anchor.get('role', '')}" if anchor.get("role") else ""
+                            confidence = f" confidence={anchor.get('confidence', '')}" if anchor.get("confidence") else ""
+                            lines.append(f"    - {anchor.get('kind', '')}: {anchor.get('ref', '')}{role}{confidence}")
+                    flow_hints = [h for h in flow.get("trace_hints", []) if isinstance(h, dict)]
+                    if flow_hints:
+                        lines.append("    trace_hints:")
+                        for hint in flow_hints:
+                            api = f" --api {hint.get('api')}" if hint.get("api") else ""
+                            lines.append(f"    - --from {hint.get('from', '')}{api} --max-depth {hint.get('max_depth', 8)}")
+                    flow_gaps = [g for g in flow.get("gaps", []) if g]
+                    if flow_gaps:
+                        lines.append("    gaps:")
+                        for gap in flow_gaps:
+                            lines.append(f"    - {gap}")
+                    accepted_gaps = [g for g in flow.get("accepted_gaps", []) if g]
+                    if accepted_gaps:
+                        lines.append("    accepted_gaps:")
+                        for gap in accepted_gaps:
+                            lines.append(f"    - {_format_accepted_gap(gap)}")
+            gaps = [g for g in scenario.get("gaps", []) if g]
+            if gaps:
+                lines.append("  gaps:")
+                for gap in gaps:
+                    lines.append(f"  - {gap}")
+            accepted_gaps = [g for g in scenario.get("accepted_gaps", []) if g]
+            if accepted_gaps:
+                lines.append("  accepted_gaps:")
+                for gap in accepted_gaps:
+                    lines.append(f"  - {_format_accepted_gap(gap)}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def format_validation_result(result: BusinessValidationResult) -> str:
+    lines = [
+        "Business map validation:",
+        f"- concepts: {result.concept_count}",
+        f"- scenarios: {result.scenario_count}",
+        f"- anchors: {result.anchor_count}",
+        f"- trace_hints: {result.trace_hint_count}",
+        f"- status: {'OK' if result.ok else 'STALE'}",
+    ]
+    if result.missing_anchors:
+        lines.append("")
+        lines.append("Missing anchors:")
+        for item in result.missing_anchors:
+            flow = f" / {item.get('flow')}" if item.get("flow") else ""
+            lines.append(
+                f"- {item.get('concept')} / {item.get('scenario')}{flow} {item.get('kind')} "
+                f"{item.get('ref')} role={item.get('role', '')}"
+            )
+    if result.missing_trace_refs:
+        lines.append("")
+        lines.append("Missing trace refs:")
+        for item in result.missing_trace_refs:
+            flow = f" / {item.get('flow')}" if item.get("flow") else ""
+            lines.append(f"- {item.get('concept')} / {item.get('scenario')}{flow} {item.get('field')}={item.get('ref')}")
+    return "\n".join(lines)
+
+
+def format_lint_result(result: BusinessLintResult) -> str:
+    lines = [
+        "Business map lint:",
+        f"- errors: {len(result.errors)}",
+        f"- warnings: {len(result.warnings)}",
+        f"- status: {'OK' if result.ok else 'FAILED'}",
+    ]
+    if result.issues:
+        lines.append("")
+        lines.append("Issues:")
+        for issue in result.issues:
+            lines.append(f"- [{issue.level}] {issue.path}: {issue.message}")
+    return "\n".join(lines)
+
+
+def trace_business(
+    *,
+    map_path: Path,
+    graph_path: Path,
+    concept_query: str,
+    scenario_query: str = "",
+    flow_query: str = "",
+    max_depth: int | None = None,
+    include_sources: bool = False,
+) -> str:
+    data = load_business_map(map_path)
+    concept = find_concept(data, concept_query)
+    scenarios = find_scenarios(concept, scenario_query)
+    runnable = [
+        scenario
+        for scenario in scenarios
+        if str(scenario.get("status", "")) != "unexplored" and _scenario_trace_items(scenario, flow_query)
+    ]
+    if scenario_query and not runnable:
+        scenario = scenarios[0]
+        flow = find_flow(scenario, flow_query) if flow_query else None
+        owner = flow or scenario
+        gaps = _compact_gap_items([g for g in owner.get("gaps", []) if g])
+        accepted_gaps = _compact_gap_items([g for g in owner.get("accepted_gaps", []) if g])
+        boundary_lines = []
+        if gaps:
+            boundary_lines.append("Gaps:")
+            boundary_lines.extend(f"- {gap}" for gap in gaps)
+        if accepted_gaps:
+            boundary_lines.append("Accepted gaps:")
+            boundary_lines.extend(f"- {gap}" for gap in accepted_gaps)
+        return "\n".join(
+            [
+                f"Concept: {concept.get('name', concept.get('id', ''))}",
+                f"Scenario: {scenario.get('name', scenario.get('id', ''))} status={scenario.get('status', '')}",
+                f"Flow: {flow.get('name', flow.get('id', ''))} status={flow.get('status', scenario.get('status', ''))}" if flow else "",
+                owner.get("summary", ""),
+                *boundary_lines,
+                "No trace_hints are available yet.",
+            ]
+        ).strip()
+
+    lines = [
+        f"Business concept: {concept.get('name', concept.get('id', ''))} ({concept.get('id', '')})",
+        f"Graph: {graph_path}",
+        f"Map: {map_path}",
+    ]
+    for scenario in runnable:
+        lines.extend(
+            [
+                "",
+                f"Scenario: {scenario.get('name', scenario.get('id', ''))} ({scenario.get('id', '')}) status={scenario.get('status', '')}",
+            ]
+        )
+        if scenario.get("summary"):
+            lines.append(f"Summary: {scenario.get('summary')}")
+        if flow_query:
+            flow = find_flow(scenario, flow_query)
+            if flow is not None:
+                lines.append(f"Flow: {flow.get('name', flow.get('id', ''))} ({flow.get('id', '')}) status={flow.get('status', scenario.get('status', ''))}")
+                if flow.get("summary"):
+                    lines.append(f"Flow summary: {flow.get('summary')}")
+                if flow.get("verification_scope"):
+                    lines.append(f"Flow verification scope: {flow.get('verification_scope')}")
+                gaps = _compact_gap_items([g for g in flow.get("gaps", []) if g])
+                accepted_gaps = _compact_gap_items([g for g in flow.get("accepted_gaps", []) if g])
+                if gaps:
+                    lines.append("Flow gaps:")
+                    lines.extend(f"- {gap}" for gap in gaps)
+                if accepted_gaps:
+                    lines.append("Flow accepted gaps:")
+                    lines.extend(f"- {gap}" for gap in accepted_gaps)
+        elif scenario.get("accepted_gaps") or scenario.get("gaps"):
+            gaps = _compact_gap_items([g for g in scenario.get("gaps", []) if g])
+            accepted_gaps = _compact_gap_items([g for g in scenario.get("accepted_gaps", []) if g])
+            if gaps:
+                lines.append("Scenario gaps:")
+                lines.extend(f"- {gap}" for gap in gaps)
+            if accepted_gaps:
+                lines.append("Scenario accepted gaps:")
+                lines.extend(f"- {gap}" for gap in accepted_gaps)
+        for idx, (hint, flow_id, constraints) in enumerate(_scenario_trace_items(scenario, flow_query), start=1):
+            depth = max_depth if max_depth is not None else int(hint.get("max_depth", 8) or 8)
+            flow_label = f" [{flow_id}]" if flow_id else ""
+            lines.extend(["", f"Trace hint {idx}{flow_label}: --from {hint.get('from', '')}" + (f" --api {hint.get('api')}" if hint.get("api") else "")])
+            if constraints["prefer_repos"] or constraints["exclude_repos"]:
+                lines.append(
+                    "Search constraints: "
+                    f"prefer_repos={', '.join(constraints['prefer_repos']) or '-'} "
+                    f"exclude_repos={', '.join(constraints['exclude_repos']) or '-'}"
+                )
+            try:
+                lines.append(
+                    trace_graph_main(
+                        graph_path,
+                        from_query=str(hint.get("from", "")),
+                        api_query=str(hint.get("api", "")),
+                        max_depth=depth,
+                        include_sources=include_sources,
+                        prefer_repos=constraints["prefer_repos"],
+                        exclude_repos=constraints["exclude_repos"],
+                    )
+                )
+            except Exception as exc:
+                lines.append(f"[trace failed] {exc}")
+
+    unexplored = [s for s in scenarios if str(s.get("status", "")) == "unexplored"]
+    if unexplored:
+        lines.append("")
+        lines.append("Unexplored scenarios:")
+        for scenario in unexplored:
+            lines.append(f"- {scenario.get('name', scenario.get('id', ''))}: {scenario.get('summary', '')}")
+    return "\n".join(lines)
+
+
+def query_business(
+    *,
+    map_path: Path,
+    graph_path: Path | None,
+    query: str,
+    top_k: int = 5,
+    max_depth: int | None = None,
+    include_sources: bool = False,
+    run_trace: bool = False,
+) -> dict:
+    data = load_business_map(map_path)
+    match = match_business_query(data, query, top_k=top_k)
+    result: dict = {
+        "query": query,
+        "map": str(map_path),
+        "graph": str(graph_path) if graph_path else None,
+        "match": match,
+        "business_context": _business_context(data, query),
+        "trace": None,
+        "graph_matches": [],
+        "next_action": "",
+    }
+    best = match.get("best")
+    if match.get("status") == "matched" and best and run_trace and graph_path is not None:
+        if best.get("scenario"):
+            result["trace"] = trace_business(
+                map_path=map_path,
+                graph_path=graph_path,
+                concept_query=str(best.get("concept") or ""),
+                scenario_query=str(best.get("scenario") or ""),
+                flow_query=str(best.get("flow") or ""),
+                max_depth=max_depth,
+                include_sources=include_sources,
+            )
+            result["next_action"] = "answer_from_trace_and_read_source_if_field_level_detail_is_needed"
+        else:
+            result["next_action"] = "matched_concept_list_or_trace_relevant_scenarios"
+    elif match.get("status") == "matched":
+        result["next_action"] = "matched_business_scope_trace_or_read_source_if_needed"
+    else:
+        result["next_action"] = "no_business_match_use_business_context_for_boundaries_then_search_graph_and_read_source"
+
+    if graph_path is not None and match.get("status") == "none":
+        result["graph_matches"] = search_graph_main_matches(graph_path, query, top_k=10)
+    return result