Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(kg): synthesize a behavior-oriented domain graph (domain/flow/step) (#577)
Raghav Chamadiyae5b93db5ef5d
diff --git a/packages/core/alembic/versions/0032_health_dimensions.py b/packages/core/alembic/versions/0033_health_dimensions.pysimilarity index 85%rename from packages/core/alembic/versions/0032_health_dimensions.pyrename to packages/core/alembic/versions/0033_health_dimensions.pyindex 6356964d2..7a86975a9 100644--- a/packages/core/alembic/versions/0032_health_dimensions.py+++ b/packages/core/alembic/versions/0033_health_dimensions.py@@ -13,9 +13,13 @@ storage for that split:All columns are additive and nullable with no backfill - the next index recomputerepopulates them. The overall surfaced score is unchanged.-Revision ID: 0032-Revises: 0031+Revision ID: 0033+Revises: 0032Create Date: 2026-06-20++NOTE: originally authored as 0032 in parallel with 0032_external_system_io_kind;+rebased onto that revision so the migration chain stays linear (two revisions+sharing id 0032 left alembic with two heads)."""from __future__ import annotations@@ -26,8 +30,8 @@ import sqlalchemy as safrom alembic import op# revision identifiers-revision: str = "0032"-down_revision: str | None = "0031"+revision: str = "0033"+down_revision: str | None = "0032"branch_labels: str | Sequence[str] | None = Nonedepends_on: str | Sequence[str] | None = Nonediff --git a/packages/core/alembic/versions/0034_domain_graph.py b/packages/core/alembic/versions/0034_domain_graph.pynew file mode 100644index 000000000..f44e4d08e--- /dev/null+++ b/packages/core/alembic/versions/0034_domain_graph.py@@ -0,0 +1,92 @@+"""Domain graph tables: behavior-oriented Domain / Flow / Step nodes + edges.++Adds the persistence for the synthesized domain graph (the artifact that+answers "what does the system do?"), mirroring the structural graph's+discriminated single-table-of-nodes + typed-edges shape:++- ``domain_graph_nodes`` holds Domain, Flow, and Step rows (``kind``), with the+ renderable wiki page content (``page_title`` / ``page_content``) stored+ alongside the structural fields on domain/flow rows.+- ``domain_graph_edges`` holds ``contains_flow`` / ``flow_step`` /+ ``cross_domain`` edges.++Additive and self-contained; no existing table is touched.++Revision ID: 0034+Revises: 0033+Create Date: 2026-06-23+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0034"+down_revision: str | None = "0033"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.create_table(+ "domain_graph_nodes",+ sa.Column("id", sa.String(32), primary_key=True),+ sa.Column(+ "repository_id",+ sa.String(32),+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),+ nullable=False,+ ),+ sa.Column("node_id", sa.Text, nullable=False),+ sa.Column("kind", sa.String(16), nullable=False),+ sa.Column("name", sa.Text, nullable=False, server_default=""),+ sa.Column("summary", sa.Text, nullable=False, server_default=""),+ sa.Column("parent_id", sa.Text, nullable=True),+ sa.Column("step_order", sa.Integer, nullable=True),+ sa.Column("implements_json", sa.Text, nullable=False, server_default="[]"),+ sa.Column("display_order", sa.Integer, nullable=False, server_default="0"),+ sa.Column("page_title", sa.Text, nullable=False, server_default=""),+ sa.Column("page_content", sa.Text, nullable=False, server_default=""),+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),+ sa.UniqueConstraint("repository_id", "node_id", name="uq_domain_graph_node"),+ )+ op.create_index(+ "ix_domain_graph_nodes_repo", "domain_graph_nodes", ["repository_id"]+ )++ op.create_table(+ "domain_graph_edges",+ sa.Column("id", sa.String(32), primary_key=True),+ sa.Column(+ "repository_id",+ sa.String(32),+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),+ nullable=False,+ ),+ sa.Column("source_node_id", sa.Text, nullable=False),+ sa.Column("target_node_id", sa.Text, nullable=False),+ sa.Column("edge_type", sa.String(32), nullable=False),+ sa.Column("weight", sa.Float, nullable=False, server_default="0"),+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),+ sa.UniqueConstraint(+ "repository_id",+ "source_node_id",+ "target_node_id",+ "edge_type",+ name="uq_domain_graph_edge",+ ),+ )+ op.create_index(+ "ix_domain_graph_edges_repo", "domain_graph_edges", ["repository_id"]+ )+++def downgrade() -> None:+ op.drop_index("ix_domain_graph_edges_repo", table_name="domain_graph_edges")+ op.drop_table("domain_graph_edges")+ op.drop_index("ix_domain_graph_nodes_repo", table_name="domain_graph_nodes")+ op.drop_table("domain_graph_nodes")diff --git a/packages/core/src/repowise/core/analysis/knowledge_graph.py b/packages/core/src/repowise/core/analysis/knowledge_graph.pyindex 573412076..252685892 100644--- a/packages/core/src/repowise/core/analysis/knowledge_graph.py+++ b/packages/core/src/repowise/core/analysis/knowledge_graph.py@@ -30,6 +30,11 @@ class KnowledgeGraphResult:# populates this; empty means the key is omitted from ``to_dict`` so the# flag-off artifact stays byte-identical.modules: list[dict] = field(default_factory=list)+ # Behavior-oriented domain graph (Domain -> Flow -> Step), synthesized by the+ # generation pipeline after pages exist. Serialized as a ``DomainGraph`` dict+ # (see ``core.generation.domain_graph``); empty/omitted on the deterministic+ # skeleton so the uncurated export's byte shape is unchanged.+ domain_graph: dict = field(default_factory=dict)fingerprint: str = ""def to_dict(self) -> dict:@@ -72,6 +77,11 @@ class KnowledgeGraphResult:out["modules"] = [{**m, "nodeIds": sorted(m.get("nodeIds", []))} for m in self.modules]+ if self.domain_graph:+ # Additive key: present only when the domain graph was synthesized,+ # so the skeleton/uncurated export's byte shape is unchanged. Lets+ # the graph round-trip through ``knowledge-graph.json`` for caching.+ out["domain_graph"] = self.domain_graphreturn out@classmethod@@ -88,6 +98,7 @@ class KnowledgeGraphResult:layers=data.get("layers", []),tour=data.get("tour", []),modules=data.get("modules", []),+ domain_graph=data.get("domain_graph", {}),)diff --git a/packages/core/src/repowise/core/generation/domain_graph/__init__.py b/packages/core/src/repowise/core/generation/domain_graph/__init__.pynew file mode 100644index 000000000..f21d0b5fa--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/__init__.py@@ -0,0 +1,31 @@+"""Behavior-oriented domain graph (Domain -> Flow -> Step).++A synthesized artifact layered on top of the structural knowledge graph that+answers "what does this system do?". Built after wiki pages exist, from layers++ file summaries + the heaviest import edges (not raw source), with a fixed,+bounded LLM budget. See :mod:`.synthesis` for the orchestration and+:mod:`.models` for the in-memory shape.+"""++from __future__ import annotations++from .models import (+ CrossDomainEdge,+ DomainGraph,+ DomainNode,+ FlowNode,+ StepNode,+)+from .persistence_map import flatten_edges, flatten_nodes+from .synthesis import synthesize_domain_graph++__all__ = [+ "CrossDomainEdge",+ "DomainGraph",+ "DomainNode",+ "FlowNode",+ "StepNode",+ "flatten_edges",+ "flatten_nodes",+ "synthesize_domain_graph",+]diff --git a/packages/core/src/repowise/core/generation/domain_graph/cache.py b/packages/core/src/repowise/core/generation/domain_graph/cache.pynew file mode 100644index 000000000..329882d47--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/cache.py@@ -0,0 +1,57 @@+"""Per-domain structural fingerprint + reuse (mirrors page-cache behaviour).++A domain's flows/steps only need re-synthesizing when its member set changes+structurally. The fingerprint hashes the member node ids together with their+best summaries (which themselves change only when the underlying source does),+so an unchanged domain can reuse the prior run's flows without an LLM call.+Pure - no DB, no LLM.+"""++from __future__ import annotations++import hashlib++from .models import DomainGraph, DomainNode, FlowNode+++def domain_fingerprint(+ member_node_ids: list[str],+ summary_by_node_id: dict[str, str],+ internal_edges: list[tuple[str, str]] = (),+) -> str:+ """Stable hash over the members (id + summary) and their internal coupling.++ Folding the internal import edges in means a coupling change among+ otherwise-unchanged member files still invalidates the cache, so reused+ flows can never reflect stale structure.+ """+ hasher = hashlib.sha256()+ for nid in sorted(member_node_ids):+ hasher.update(nid.encode("utf-8"))+ hasher.update(b"\x00")+ hasher.update((summary_by_node_id.get(nid, "")).encode("utf-8"))+ hasher.update(b"\x01")+ hasher.update(b"\x02")+ for src, tgt in sorted(internal_edges):+ hasher.update(src.encode("utf-8"))+ hasher.update(b"\x00")+ hasher.update(tgt.encode("utf-8"))+ hasher.update(b"\x01")+ return hasher.hexdigest()+++def reuse_flows(+ prior: DomainGraph | None,+ domain: DomainNode,+) -> list[FlowNode] | None:+ """Return the prior run's flows for *domain* when its fingerprint matches.++ Matched by slug + fingerprint; ``None`` means "re-synthesize". A prior+ domain with an empty fingerprint never matches (forces a refresh).+ """+ if prior is None or not domain.fingerprint:+ return None+ for prev in prior.domains:+ if prev.slug == domain.slug and prev.fingerprint == domain.fingerprint and prev.flows:+ return [FlowNode.from_dict(f.to_dict()) for f in prev.flows]+ return Nonediff --git a/packages/core/src/repowise/core/generation/domain_graph/context.py b/packages/core/src/repowise/core/generation/domain_graph/context.pynew file mode 100644index 000000000..34cd3af06--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/context.py@@ -0,0 +1,196 @@+"""(a) Context assembly for domain synthesis.++Pure functions that gather the bounded context the LLM prompts need, drawn from+the already-generated structural artifacts (enriched layers, file node summaries,+the heaviest import edges) - never from raw source. No DB, no LLM, no I/O, so+every function here is unit-testable against small fixture dicts.++Two contexts are assembled:++* a per-layer **cluster** summary feeding the domain-naming prompt, and+* a per-domain **member** view (ranked files + summaries + internal import+ edges) feeding the per-domain flow/step prompt.++Cross-domain dependency edges are derived structurally from the import edges+that cross a domain boundary.+"""++from __future__ import annotations++from dataclasses import dataclass, field++from .models import CrossDomainEdge, DomainNode+++@dataclass+class LayerCluster:+ """Compact view of one structural layer for the naming prompt."""++ layer_id: str+ name: str+ description: str+ file_count: int+ top_files: list[str] = field(default_factory=list)+++@dataclass+class FileContext:+ """A member file plus its best available one-line summary."""++ node_id: str # "file:<path>"+ path: str+ summary: str = ""+++def _is_file_node(node: dict) -> bool:+ nid = node.get("id")+ return isinstance(nid, str) and nid.startswith("file:")+++def _node_path(node: dict) -> str:+ return node.get("filePath") or str(node.get("id", "")).removeprefix("file:")+++def _best_summary(node: dict, page_summaries: dict[str, str]) -> str:+ """Prefer a rich wiki-page summary; fall back to the node's own summary."""+ path = _node_path(node)+ return page_summaries.get(path) or str(node.get("summary") or "")+++def file_nodes_by_id(nodes: list[dict]) -> dict[str, dict]:+ return {n["id"]: n for n in nodes if _is_file_node(n) and n.get("id")}+++def _rank(node: dict) -> float:+ try:+ return float(node.get("pagerank") or 0.0)+ except (TypeError, ValueError):+ return 0.0+++def build_layer_clusters(+ layers: list[dict],+ nodes: list[dict],+ max_files: int = 12,+) -> list[LayerCluster]:+ """One :class:`LayerCluster` per structural layer, ranked top files first.++ Empty layers (no file members) are dropped - a domain can only be named+ from a real cluster.+ """+ by_id = file_nodes_by_id(nodes)+ clusters: list[LayerCluster] = []+ for layer in layers:+ member_ids = [nid for nid in layer.get("nodeIds", []) if nid in by_id]+ if not member_ids:+ continue+ ranked = sorted(member_ids, key=lambda nid: _rank(by_id[nid]), reverse=True)+ top = [_node_path(by_id[nid]) for nid in ranked[:max_files]]+ clusters.append(+ LayerCluster(+ layer_id=str(layer.get("id", "")),+ name=str(layer.get("name", "")),+ description=str(layer.get("description", "")),+ file_count=len(member_ids),+ top_files=top,+ )+ )+ return clusters+++def member_node_ids(layer_ids: list[str], layers: list[dict], nodes: list[dict]) -> list[str]:+ """Union of the file node ids belonging to *layer_ids* (deduped, sorted)."""+ by_id = file_nodes_by_id(nodes)+ wanted = set(layer_ids)+ out: set[str] = set()+ for layer in layers:+ if str(layer.get("id", "")) in wanted:+ out.update(nid for nid in layer.get("nodeIds", []) if nid in by_id)+ return sorted(out)+++def build_member_context(+ domain: DomainNode,+ nodes: list[dict],+ page_summaries: dict[str, str],+ max_files: int = 25,+) -> list[FileContext]:+ """Ranked member files with their best summaries, for the flow prompt."""+ by_id = file_nodes_by_id(nodes)+ members = [nid for nid in domain.member_node_ids if nid in by_id]+ ranked = sorted(members, key=lambda nid: _rank(by_id[nid]), reverse=True)+ out: list[FileContext] = []+ for nid in ranked[:max_files]:+ node = by_id[nid]+ out.append(+ FileContext(+ node_id=nid,+ path=_node_path(node),+ summary=_best_summary(node, page_summaries),+ )+ )+ return out+++def heaviest_internal_edges(+ member_node_ids_set: set[str],+ edges: list[dict],+ top: int = 15,+) -> list[tuple[str, str]]:+ """The highest-weight import edges with both endpoints inside the domain.++ Returns ``(source_path, target_path)`` pairs so the prompt can show real+ "A is used by B" coupling without leaking node-id noise.+ """+ scored: list[tuple[float, str, str]] = []+ for edge in edges:+ src = edge.get("source", "")+ tgt = edge.get("target", "")+ if src in member_node_ids_set and tgt in member_node_ids_set:+ weight = float(edge.get("weight", 1) or 1)+ scored.append((weight, src, tgt))+ scored.sort(key=lambda t: (-t[0], t[1], t[2]))+ return [+ (src.removeprefix("file:"), tgt.removeprefix("file:")) for _, src, tgt in scored[:top]+ ]+++def internal_edge_ids(+ member_node_ids_set: set[str],+ edges: list[dict],+) -> list[tuple[str, str]]:+ """All ``(source, target)`` node-id pairs with both ends inside the member+ set, sorted. Feeds the domain fingerprint so a coupling change among+ otherwise-unchanged members still forces a re-synthesis."""+ pairs = {+ (edge.get("source", ""), edge.get("target", ""))+ for edge in edges+ if edge.get("source", "") in member_node_ids_set+ and edge.get("target", "") in member_node_ids_set+ }+ return sorted(pairs)+++def derive_cross_domain_edges(+ domains: list[DomainNode],+ edges: list[dict],+) -> list[CrossDomainEdge]:+ """Aggregate import edges that cross a domain boundary into domain->domain+ dependency edges weighted by the count of crossing imports."""+ domain_of: dict[str, str] = {}+ for domain in domains:+ for nid in domain.member_node_ids:+ domain_of[nid] = domain.id++ counts: dict[tuple[str, str], int] = {}+ for edge in edges:+ src_domain = domain_of.get(edge.get("source", ""))+ tgt_domain = domain_of.get(edge.get("target", ""))+ if src_domain and tgt_domain and src_domain != tgt_domain:+ key = (src_domain, tgt_domain)+ counts[key] = counts.get(key, 0) + 1++ return [+ CrossDomainEdge(source=src, target=tgt, weight=weight)+ for (src, tgt), weight in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))+ ]diff --git a/packages/core/src/repowise/core/generation/domain_graph/models.py b/packages/core/src/repowise/core/generation/domain_graph/models.pynew file mode 100644index 000000000..4f7b96c78--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/models.py@@ -0,0 +1,180 @@+"""In-memory dataclasses for the behavior-oriented domain graph.++The structural knowledge graph answers "what is the code?"; the domain graph+answers "what does the system do?". It has three levels:++* :class:`DomainNode` - a capability / bounded context (e.g. "Indexing+ Pipeline"), backed by one or more structural layers.+* :class:`FlowNode` - a process within a domain (e.g. "Index a repository+ from scratch").+* :class:`StepNode` - an ordered stage in a flow, mapped to the concrete+ file/symbol node ids that implement it.++These are pure data with ``to_dict`` / ``from_dict`` round-trips so the graph+can travel through the ``knowledge-graph.json`` artifact and be validated by the+reviewer without a DB or an LLM. Flattening to persistable nodes/edges lives in+:mod:`.persistence_map`; rendering to wiki page content lives in :mod:`.render`.+"""++from __future__ import annotations++from dataclasses import dataclass, field++# Domain-graph edge types (mirrors the structural graph's typed-edge model).+EDGE_CONTAINS_FLOW = "contains_flow"+EDGE_FLOW_STEP = "flow_step"+EDGE_CROSS_DOMAIN = "cross_domain"+++@dataclass+class StepNode:+ """One ordered stage of a flow, mapped to real implementing node ids."""++ order: int+ name: str+ summary: str = ""+ # Real file/symbol node ids ("file:<path>") that implement this step.+ # Always validated against the structural graph before persistence.+ implements: list[str] = field(default_factory=list)++ def id(self, flow_id: str) -> str:+ return f"step:{flow_id.removeprefix('flow:')}/{self.order}"++ def to_dict(self) -> dict:+ return {+ "order": self.order,+ "name": self.name,+ "summary": self.summary,+ "implements": list(self.implements),+ }++ @classmethod+ def from_dict(cls, data: dict) -> StepNode:+ return cls(+ order=int(data.get("order", 0)),+ name=str(data.get("name", "")),+ summary=str(data.get("summary", "")),+ implements=list(data.get("implements", [])),+ )+++@dataclass+class FlowNode:+ """A process within a domain - an ordered sequence of steps."""++ slug: str+ name: str+ summary: str = ""+ steps: list[StepNode] = field(default_factory=list)++ def id(self, domain_id: str) -> str:+ return f"flow:{domain_id.removeprefix('domain:')}/{self.slug}"++ def to_dict(self) -> dict:+ return {+ "slug": self.slug,+ "name": self.name,+ "summary": self.summary,+ "steps": [s.to_dict() for s in self.steps],+ }++ @classmethod+ def from_dict(cls, data: dict) -> FlowNode:+ return cls(+ slug=str(data.get("slug", "")),+ name=str(data.get("name", "")),+ summary=str(data.get("summary", "")),+ steps=[StepNode.from_dict(s) for s in data.get("steps", [])],+ )+++@dataclass+class DomainNode:+ """A capability / bounded context backed by structural layers."""++ slug: str+ name: str+ summary: str = ""+ # Structural layer ids this domain is built from.+ member_layer_ids: list[str] = field(default_factory=list)+ # Union of the member layers' file node ids ("file:<path>"). The validation+ # surface flows/steps may map into.+ member_node_ids: list[str] = field(default_factory=list)+ flows: list[FlowNode] = field(default_factory=list)+ # Structural fingerprint of the member set; lets a re-index reuse an+ # unchanged domain's flows/steps without a fresh LLM call.+ fingerprint: str = ""++ @property+ def id(self) -> str:+ return f"domain:{self.slug}"++ def to_dict(self) -> dict:+ return {+ "slug": self.slug,+ "name": self.name,+ "summary": self.summary,+ "member_layer_ids": list(self.member_layer_ids),+ "member_node_ids": list(self.member_node_ids),+ "flows": [f.to_dict() for f in self.flows],+ "fingerprint": self.fingerprint,+ }++ @classmethod+ def from_dict(cls, data: dict) -> DomainNode:+ return cls(+ slug=str(data.get("slug", "")),+ name=str(data.get("name", "")),+ summary=str(data.get("summary", "")),+ member_layer_ids=list(data.get("member_layer_ids", [])),+ member_node_ids=list(data.get("member_node_ids", [])),+ flows=[FlowNode.from_dict(f) for f in data.get("flows", [])],+ fingerprint=str(data.get("fingerprint", "")),+ )+++@dataclass+class CrossDomainEdge:+ """A dependency from one domain to another, weighted by import volume."""++ source: str # "domain:<slug>"+ target: str # "domain:<slug>"+ weight: int = 0++ def to_dict(self) -> dict:+ return {"source": self.source, "target": self.target, "weight": self.weight}++ @classmethod+ def from_dict(cls, data: dict) -> CrossDomainEdge:+ return cls(+ source=str(data.get("source", "")),+ target=str(data.get("target", "")),+ weight=int(data.get("weight", 0)),+ )+++@dataclass+class DomainGraph:+ """The full behavior-oriented graph: domains, their flows/steps, and the+ cross-domain dependency edges between them."""++ domains: list[DomainNode] = field(default_factory=list)+ cross_domain: list[CrossDomainEdge] = field(default_factory=list)++ def is_empty(self) -> bool:+ return not self.domains++ def to_dict(self) -> dict:+ return {+ "domains": [d.to_dict() for d in self.domains],+ "cross_domain": [e.to_dict() for e in self.cross_domain],+ }++ @classmethod+ def from_dict(cls, data: dict) -> DomainGraph:+ if not isinstance(data, dict):+ return cls()+ return cls(+ domains=[DomainNode.from_dict(d) for d in data.get("domains", [])],+ cross_domain=[CrossDomainEdge.from_dict(e) for e in data.get("cross_domain", [])],+ )diff --git a/packages/core/src/repowise/core/generation/domain_graph/parsing.py b/packages/core/src/repowise/core/generation/domain_graph/parsing.pynew file mode 100644index 000000000..4cc193385--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/parsing.py@@ -0,0 +1,151 @@+"""(c) Response parsing + node-id resolution/validation.++Pure functions that turn raw LLM JSON into validated :mod:`.models` objects.+The load-bearing guarantee here is **no hallucinated membership**: a domain may+only claim layer ids that were offered, and a step may only implement member+file paths that exist. Unknown ids are dropped (not trusted), empty steps and+flows are pruned, and step orders are renumbered contiguously. Everything is+testable with fixture strings - no LLM, no DB.+"""++from __future__ import annotations++import json++import structlog++from .models import DomainNode, FlowNode, StepNode++logger = structlog.get_logger(__name__)+++def parse_json(content: str) -> dict | None:+ """Extract a JSON object from an LLM response, tolerating code fences."""+ content = (content or "").strip()+ if content.startswith("```"):+ content = "\n".join(+ line for line in content.split("\n") if not line.strip().startswith("```")+ )+ try:+ return json.loads(content)+ except json.JSONDecodeError:+ start = content.find("{")+ end = content.rfind("}") + 1+ if start >= 0 and end > start:+ try:+ return json.loads(content[start:end])+ except json.JSONDecodeError:+ return None+ return None+++def _slugify(value: str, fallback: str) -> str:+ cleaned = "".join(c if c.isalnum() else "-" for c in value.lower())+ cleaned = "-".join(part for part in cleaned.split("-") if part)+ return cleaned or fallback+++def parse_domains(content: str, valid_layer_ids: set[str]) -> list[DomainNode]:+ """Parse the domain-naming response into domains with validated membership.++ A layer is assigned to the first domain that claims it (one domain per+ cluster). Domains left with no valid layer are dropped - a domain must be+ grounded in a real cluster. ``member_node_ids`` is filled in later by the+ caller once the layer->file mapping is known.+ """+ parsed = parse_json(content)+ if not parsed or not isinstance(parsed.get("domains"), list):+ return []++ domains: list[DomainNode] = []+ claimed: set[str] = set()+ seen_slugs: set[str] = set()+ rejected = 0+ for i, item in enumerate(parsed["domains"]):+ if not isinstance(item, dict):+ continue+ members: list[str] = []+ for lid in item.get("member_layer_ids", []):+ if lid in valid_layer_ids and lid not in claimed:+ members.append(lid)+ claimed.add(lid)+ elif lid not in valid_layer_ids:+ rejected += 1+ if not members:+ continue+ name = str(item.get("name", "")).strip() or f"Domain {i + 1}"+ slug = _slugify(str(item.get("slug", "")) or name, f"domain-{i + 1}")+ if slug in seen_slugs:+ slug = f"{slug}-{i + 1}"+ seen_slugs.add(slug)+ domains.append(+ DomainNode(+ slug=slug,+ name=name,+ summary=str(item.get("summary", "")).strip(),+ member_layer_ids=members,+ )+ )+ if rejected:+ logger.warning("domain_graph_rejected_unknown_layers", count=rejected)+ return domains+++def resolve_flows(content: str, member_node_ids: set[str]) -> list[FlowNode]:+ """Parse the flow response, keeping only steps that implement real members.++ *member_node_ids* are the domain's file node ids ("file:<path>"). Each+ step's ``implements`` paths are normalized to that form and filtered to the+ member set; a step with no surviving member is dropped, a flow with no+ surviving step is dropped, and step orders are renumbered 1..N.+ """+ parsed = parse_json(content)+ if not parsed or not isinstance(parsed.get("flows"), list):+ return []++ flows: list[FlowNode] = []+ seen_slugs: set[str] = set()+ rejected = 0+ for i, raw_flow in enumerate(parsed["flows"]):+ if not isinstance(raw_flow, dict):+ continue+ steps: list[StepNode] = []+ for raw_step in raw_flow.get("steps", []):+ if not isinstance(raw_step, dict):+ continue+ implements: list[str] = []+ for ref in raw_step.get("implements", []):+ nid = ref if str(ref).startswith("file:") else f"file:{ref}"+ if nid in member_node_ids:+ if nid not in implements:+ implements.append(nid)+ else:+ rejected += 1+ if not implements:+ continue+ steps.append(+ StepNode(+ order=len(steps) + 1,+ name=str(raw_step.get("name", "")).strip() or f"Step {len(steps) + 1}",+ summary=str(raw_step.get("summary", "")).strip(),+ implements=implements,+ )+ )+ if not steps:+ continue+ name = str(raw_flow.get("name", "")).strip() or f"Flow {i + 1}"+ slug = _slugify(str(raw_flow.get("slug", "")) or name, f"flow-{i + 1}")+ if slug in seen_slugs:+ slug = f"{slug}-{i + 1}"+ seen_slugs.add(slug)+ flows.append(+ FlowNode(+ slug=slug,+ name=name,+ summary=str(raw_flow.get("summary", "")).strip(),+ steps=steps,+ )+ )+ if rejected:+ logger.warning("domain_graph_rejected_unknown_node_ids", count=rejected)+ return flowsdiff --git a/packages/core/src/repowise/core/generation/domain_graph/persistence_map.py b/packages/core/src/repowise/core/generation/domain_graph/persistence_map.pynew file mode 100644index 000000000..1efd0a755--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/persistence_map.py@@ -0,0 +1,118 @@+"""(d) Persistence mapping: flatten a :class:`DomainGraph` into storable rows.++Pure transform from the in-memory graph to the row dicts the CRUD layer writes+(``domain_graph_nodes`` / ``domain_graph_edges``), with the renderable page+content attached to domain and flow rows. Testable with fixture graphs - no DB.++Node row shape::++ {node_id, kind, name, summary, parent_id, step_order,+ implements (list[str]), page_title, page_content, display_order}++Edge row shape::++ {source_node_id, target_node_id, edge_type, weight}+"""++from __future__ import annotations++from .models import (+ EDGE_CONTAINS_FLOW,+ EDGE_CROSS_DOMAIN,+ EDGE_FLOW_STEP,+ DomainGraph,+)+from .render import render_domain_page, render_flow_page+++def flatten_nodes(+ graph: DomainGraph,+ hotspot_node_ids: set[str] | None = None,+) -> list[dict]:+ """Domain, flow, and step rows in stable, display-ordered sequence."""+ rows: list[dict] = []+ for d_order, domain in enumerate(graph.domains):+ title, _summary, content = render_domain_page(domain)+ rows.append(+ {+ "node_id": domain.id,+ "kind": "domain",+ "name": domain.name,+ "summary": domain.summary,+ "parent_id": None,+ "step_order": None,+ "implements": list(domain.member_node_ids),+ "page_title": title,+ "page_content": content,+ "display_order": d_order,+ }+ )+ for f_order, flow in enumerate(domain.flows):+ flow_id = flow.id(domain.id)+ f_title, _f_summary, f_content = render_flow_page(domain, flow, hotspot_node_ids)+ rows.append(+ {+ "node_id": flow_id,+ "kind": "flow",+ "name": flow.name,+ "summary": flow.summary,+ "parent_id": domain.id,+ "step_order": None,+ "implements": [],+ "page_title": f_title,+ "page_content": f_content,+ "display_order": f_order,+ }+ )+ for step in flow.steps:+ rows.append(+ {+ "node_id": step.id(flow_id),+ "kind": "step",+ "name": step.name,+ "summary": step.summary,+ "parent_id": flow_id,+ "step_order": step.order,+ "implements": list(step.implements),+ "page_title": "",+ "page_content": "",+ "display_order": step.order,+ }+ )+ return rows+++def flatten_edges(graph: DomainGraph) -> list[dict]:+ """contains_flow (domain->flow), flow_step (flow->step, weight=order),+ and cross_domain (domain->domain, weight=import count) edges."""+ rows: list[dict] = []+ for domain in graph.domains:+ for flow in domain.flows:+ flow_id = flow.id(domain.id)+ rows.append(+ {+ "source_node_id": domain.id,+ "target_node_id": flow_id,+ "edge_type": EDGE_CONTAINS_FLOW,+ "weight": 0.0,+ }+ )+ for step in flow.steps:+ rows.append(+ {+ "source_node_id": flow_id,+ "target_node_id": step.id(flow_id),+ "edge_type": EDGE_FLOW_STEP,+ "weight": float(step.order),+ }+ )+ for edge in graph.cross_domain:+ rows.append(+ {+ "source_node_id": edge.source,+ "target_node_id": edge.target,+ "edge_type": EDGE_CROSS_DOMAIN,+ "weight": float(edge.weight),+ }+ )+ return rowsdiff --git a/packages/core/src/repowise/core/generation/domain_graph/prompts.py b/packages/core/src/repowise/core/generation/domain_graph/prompts.pynew file mode 100644index 000000000..6b35e9105--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/prompts.py@@ -0,0 +1,102 @@+"""(b) Prompt construction for domain synthesis.++Pure string builders - no LLM, no I/O. Two prompts:++* :func:`build_domain_naming_prompt` groups structural layer clusters into+ behavior-oriented capability domains. Membership is constrained to the layer+ ids actually supplied, so the model cannot invent a cluster.+* :func:`build_flow_prompt` extracts ordered flows + steps for one domain. Each+ step's implementing files are constrained to the domain's member file paths,+ so node-id resolution can reject any hallucinated membership downstream.+"""++from __future__ import annotations++from .context import FileContext, LayerCluster++DOMAIN_NAMING_SYSTEM = (+ "You are a software architecture analyst. You group low-level code clusters "+ "into a small set of behavior-oriented capability domains that describe what "+ "the system *does* (e.g. 'Indexing Pipeline', 'Code Health', 'Persistence'). "+ "Output valid JSON only. No preamble, no markdown fences."+)++FLOW_EXTRACTION_SYSTEM = (+ "You are a software architecture analyst. For one capability domain you "+ "describe the key end-to-end processes (flows) it performs, each as an "+ "ordered list of steps, mapping every step to the specific files that "+ "implement it. Output valid JSON only. No preamble, no markdown fences."+)+++def build_domain_naming_prompt(clusters: list[LayerCluster]) -> str:+ lines = [+ "Group the code clusters below into 4-10 capability domains describing "+ "what the system does. Rules:",+ "- A domain's name is behavior-oriented (a capability), not a code layer "+ "name. Keep it 1-4 words.",+ "- member_layer_ids must each be one of the cluster ids listed below, "+ "copied verbatim. Do not invent ids.",+ "- Assign each cluster to at most one domain. It is fine to leave a "+ "purely incidental cluster (docs, tooling) out.",+ "- slug is a short lowercase-kebab identifier for the domain.",+ "",+ "Clusters:",+ ]+ for c in clusters:+ lines.append(f'\n--- cluster id "{c.layer_id}" ---')+ lines.append(f"Heuristic name: {c.name}")+ if c.description:+ lines.append(f"Description: {c.description}")+ lines.append(f"File count: {c.file_count}")+ if c.top_files:+ lines.append(f"Representative files: {', '.join(c.top_files)}")+ lines.append("")+ lines.append(+ 'Respond with: {"domains": [{"slug": "...", "name": "...", '+ '"summary": "one sentence", "member_layer_ids": ["..."]}]}'+ )+ return "\n".join(lines)+++def build_flow_prompt(+ domain_name: str,+ domain_summary: str,+ members: list[FileContext],+ internal_edges: list[tuple[str, str]],+) -> str:+ lines = [+ f'Describe the key processes (flows) of the "{domain_name}" domain.',+ ]+ if domain_summary:+ lines.append(f"Domain summary: {domain_summary}")+ lines += [+ "",+ "Rules:",+ "- Produce 1-4 flows. Each flow is a real end-to-end process in this "+ "domain (e.g. 'Index a repository from scratch').",+ "- Each flow has ordered steps starting at 1, contiguous, no gaps.",+ "- Every step's `implements` is a list of file paths chosen ONLY from "+ "the member files listed below, copied verbatim. Never invent a path.",+ "- A step maps to at least one member file. Keep summaries to one line.",+ "- slug is a short lowercase-kebab identifier for the flow.",+ "",+ "Member files (path -- summary):",+ ]+ for m in members:+ summary = m.summary.strip().replace("\n", " ")+ if len(summary) > 160:+ summary = summary[:157] + "..."+ lines.append(f"- {m.path}" + (f" -- {summary}" if summary else ""))+ if internal_edges:+ lines.append("")+ lines.append("Key internal dependencies (A is imported by B):")+ for src, tgt in internal_edges:+ lines.append(f"- {src} <- {tgt}")+ lines.append("")+ lines.append(+ 'Respond with: {"flows": [{"slug": "...", "name": "...", '+ '"summary": "one sentence", "steps": [{"order": 1, "name": "...", '+ '"summary": "one line", "implements": ["path/to/file.py"]}]}]}'+ )+ return "\n".join(lines)diff --git a/packages/core/src/repowise/core/generation/domain_graph/render.py b/packages/core/src/repowise/core/generation/domain_graph/render.pynew file mode 100644index 000000000..6dd8ed746--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/render.py@@ -0,0 +1,58 @@+"""Renderable wiki page content for domains and flows (pure).++Produces ``(title, summary, markdown)`` triples so the domain graph can be+persisted as embeddable page content alongside its structural rows. No DB, no+LLM - Phase 5 decides how to surface these; here we only render.+"""++from __future__ import annotations++from .models import DomainNode, FlowNode+++def _file_link(node_id: str) -> str:+ path = node_id.removeprefix("file:")+ return f"`{path}`"+++def render_domain_page(domain: DomainNode) -> tuple[str, str, str]:+ """A domain overview page: summary + its flows with their step counts."""+ title = domain.name+ summary = domain.summary or f"The {domain.name} capability."+ lines = [f"# {title}", "", summary, ""]+ if domain.flows:+ lines.append("## Flows")+ lines.append("")+ for flow in domain.flows:+ step_word = "step" if len(flow.steps) == 1 else "steps"+ lines.append(f"- **{flow.name}** ({len(flow.steps)} {step_word})")+ if flow.summary:+ lines.append(f" - {flow.summary}")+ return title, summary, "\n".join(lines).rstrip() + "\n"+++def render_flow_page(+ domain: DomainNode,+ flow: FlowNode,+ hotspot_node_ids: set[str] | None = None,+) -> tuple[str, str, str]:+ """A flow page: ordered steps with the files each step implements.++ When *hotspot_node_ids* is supplied, a step that touches a churn hotspot is+ annotated so the riskiest stage of the flow is visible at a glance.+ """+ hotspots = hotspot_node_ids or set()+ title = f"{flow.name} ({domain.name})"+ summary = flow.summary or f"How {domain.name.lower()} performs {flow.name.lower()}."+ lines = [f"# {flow.name}", "", f"_Part of the {domain.name} domain._", "", summary, ""]+ lines.append("## Steps")+ lines.append("")+ for step in flow.steps:+ risky = any(nid in hotspots for nid in step.implements)+ marker = " ⚠ hotspot" if risky else ""+ lines.append(f"{step.order}. **{step.name}**{marker}")+ if step.summary:+ lines.append(f" - {step.summary}")+ for nid in step.implements:+ lines.append(f" - {_file_link(nid)}")+ return title, summary, "\n".join(lines).rstrip() + "\n"diff --git a/packages/core/src/repowise/core/generation/domain_graph/synthesis.py b/packages/core/src/repowise/core/generation/domain_graph/synthesis.pynew file mode 100644index 000000000..f5ff9f7c1--- /dev/null+++ b/packages/core/src/repowise/core/generation/domain_graph/synthesis.py@@ -0,0 +1,138 @@+"""Async orchestrator for domain-graph synthesis.++Ties the pure stages together with a fixed, bounded LLM budget: one call to+name domains, then one call per domain to extract its flows/steps (skipped for+any domain whose structural fingerprint is unchanged from a prior run). The+budget is a function of the (small) domain count, never the file count.++Failures degrade gracefully: a failed naming call yields an empty graph, a+failed flow call drops only that domain. The caller wires this into+``enrich_knowledge_graph`` inside a try/except so it can never block export.+"""++from __future__ import annotations++import asyncio+from typing import Any++import structlog++from . import context+from .cache import domain_fingerprint, reuse_flows+from .models import DomainGraph, DomainNode+from .parsing import parse_domains, resolve_flows+from .prompts import (+ DOMAIN_NAMING_SYSTEM,+ FLOW_EXTRACTION_SYSTEM,+ build_domain_naming_prompt,+ build_flow_prompt,+)++logger = structlog.get_logger(__name__)+++async def synthesize_domain_graph(+ layers: list[dict],+ nodes: list[dict],+ edges: list[dict],+ llm_client: Any,+ *,+ page_summaries: dict[str, str] | None = None,+ prior: DomainGraph | None = None,+ reasoning: str = "auto",+) -> DomainGraph:+ """Synthesize the behavior-oriented domain graph from structural inputs."""+ page_summaries = page_summaries or {}+ clusters = context.build_layer_clusters(layers, nodes)+ if not clusters:+ return DomainGraph()++ valid_layer_ids = {c.layer_id for c in clusters}+ naming_prompt = build_domain_naming_prompt(clusters)+ try:+ response = await llm_client.generate(+ DOMAIN_NAMING_SYSTEM,+ naming_prompt,+ max_tokens=2048,+ temperature=0.3,+ reasoning=reasoning,+ )+ except Exception as exc:+ logger.warning("domain_graph_naming_failed", error=str(exc))+ return DomainGraph()++ domains = parse_domains(response.content, valid_layer_ids)+ if not domains:+ logger.warning("domain_graph_no_domains_parsed")+ return DomainGraph()++ # Resolve member files + fingerprint each domain so unchanged domains can+ # reuse cached flows instead of spending an LLM call.+ summary_by_id = {+ nid: context._best_summary(node, page_summaries)+ for nid, node in context.file_nodes_by_id(nodes).items()+ }+ for domain in domains:+ domain.member_node_ids = context.member_node_ids(+ domain.member_layer_ids, layers, nodes+ )+ internal = context.internal_edge_ids(set(domain.member_node_ids), edges)+ domain.fingerprint = domain_fingerprint(+ domain.member_node_ids, summary_by_id, internal+ )++ await asyncio.gather(+ *(+ _fill_flows(domain, nodes, page_summaries, edges, llm_client, prior, reasoning)+ for domain in domains+ )+ )++ # A domain with no extractable flow is an orphan; drop it so the persisted+ # graph satisfies the reviewer's no-orphan invariant.+ surviving = [d for d in domains if d.flows]+ dropped = len(domains) - len(surviving)+ if dropped:+ logger.info("domain_graph_dropped_orphan_domains", count=dropped)++ cross = context.derive_cross_domain_edges(surviving, edges)+ logger.info(+ "domain_graph_synthesized",+ domains=len(surviving),+ flows=sum(len(d.flows) for d in surviving),+ cross_domain_edges=len(cross),+ )+ return DomainGraph(domains=surviving, cross_domain=cross)+++async def _fill_flows(+ domain: DomainNode,+ nodes: list[dict],+ page_summaries: dict[str, str],+ edges: list[dict],+ llm_client: Any,+ prior: DomainGraph | None,+ reasoning: str,+) -> None:+ """Populate one domain's flows, reusing the cache or making one LLM call."""+ cached = reuse_flows(prior, domain)+ if cached is not None:+ domain.flows = cached+ logger.debug("domain_graph_flows_reused", domain=domain.slug)+ return++ members = context.build_member_context(domain, nodes, page_summaries)+ internal = context.heaviest_internal_edges(set(domain.member_node_ids), edges)+ prompt = build_flow_prompt(domain.name, domain.summary, members, internal)+ try:+ response = await llm_client.generate(+ FLOW_EXTRACTION_SYSTEM,+ prompt,+ max_tokens=3000,+ temperature=0.3,+ reasoning=reasoning,+ )+ except Exception as exc:+ logger.warning("domain_graph_flow_failed", domain=domain.slug, error=str(exc))+ return+ domain.flows = resolve_flows(response.content, set(domain.member_node_ids))diff --git a/packages/core/src/repowise/core/generation/kg_reviewer/checks.py b/packages/core/src/repowise/core/generation/kg_reviewer/checks.pyindex e5afb744e..ac28d2b6d 100644--- a/packages/core/src/repowise/core/generation/kg_reviewer/checks.py+++ b/packages/core/src/repowise/core/generation/kg_reviewer/checks.py@@ -215,6 +215,110 @@ def check_tour_sequential(tour: list[dict]) -> list[Finding]:return findings+def _domains(domain_graph: dict) -> list[dict]:+ if not isinstance(domain_graph, dict):+ return []+ domains = domain_graph.get("domains")+ return domains if isinstance(domains, list) else []+++def check_no_orphan_domains(domain_graph: dict) -> list[Finding]:+ """Every domain has at least one flow.++ CRITICAL: a domain with no flows carries no behavior (an orphan that should+ have been dropped during synthesis).+ """+ findings: list[Finding] = []+ for domain in _domains(domain_graph):+ if not domain.get("flows"):+ findings.append(Finding(+ check="domain_no_orphan",+ severity=Severity.CRITICAL,+ message=f"domain {domain.get('name', domain.get('slug', '?'))!r} has no flows",+ target=f"domain:{domain.get('slug', '')}",+ ))+ return findings+++def check_flow_has_steps(domain_graph: dict) -> list[Finding]:+ """Every flow has at least one step.++ CRITICAL: a step-less flow renders an empty page and breaks the+ flow->step edge invariant.+ """+ findings: list[Finding] = []+ for domain in _domains(domain_graph):+ for flow in domain.get("flows", []):+ if not flow.get("steps"):+ findings.append(Finding(+ check="flow_has_steps",+ severity=Severity.CRITICAL,+ message=f"flow {flow.get('name', flow.get('slug', '?'))!r} has no steps",+ target=f"flow:{domain.get('slug', '')}/{flow.get('slug', '')}",+ ))+ return findings+++def check_step_maps_to_real_node(domain_graph: dict, nodes: list[dict]) -> list[Finding]:+ """Every step maps to at least one real (existing) file node id.++ CRITICAL: a step whose ``implements`` is empty, or references a node id that+ is not a known file node, is hallucinated membership. Synthesis drops these+ by construction, so a hit here signals a synthesis/parsing regression.+ """+ findings: list[Finding] = []+ file_ids = {n["id"] for n in nodes if _is_file_node(n) and n.get("id")}+ for domain in _domains(domain_graph):+ for flow in domain.get("flows", []):+ for step in flow.get("steps", []):+ implements = step.get("implements") or []+ target = f"flow:{domain.get('slug', '')}/{flow.get('slug', '')}#{step.get('order')}"+ if not implements:+ findings.append(Finding(+ check="step_maps_to_real_node",+ severity=Severity.CRITICAL,+ message="step maps to no implementing node",+ target=target,+ ))+ continue+ unknown = [nid for nid in implements if nid not in file_ids]+ if unknown:+ findings.append(Finding(+ check="step_maps_to_real_node",+ severity=Severity.CRITICAL,+ message=f"step references {len(unknown)} unknown node id(s)",+ target=target,+ detail={"sample": sorted(unknown)[:5]},+ ))+ return findings+++def check_step_order_valid(domain_graph: dict) -> list[Finding]:+ """Each flow's step orders form a contiguous 1..N sequence.++ CRITICAL: a gap, duplicate, or non-1-based order breaks the rendered+ sequence and the weighted ``flow_step`` edges.+ """+ findings: list[Finding] = []+ for domain in _domains(domain_graph):+ for flow in domain.get("flows", []):+ steps = flow.get("steps", [])+ if not steps:+ continue+ orders = [s.get("order") for s in steps]+ if any(o is None for o in orders) or sorted(orders) != list(+ range(1, len(orders) + 1)+ ):+ findings.append(Finding(+ check="step_order_valid",+ severity=Severity.CRITICAL,+ message="flow step order is not a contiguous 1..N sequence",+ target=f"flow:{domain.get('slug', '')}/{flow.get('slug', '')}",+ detail={"orders": orders},+ ))+ return findings++def check_layer_name_category(layers: list[dict], nodes: list[dict]) -> list[Finding]:"""A layer name may not assert a runtime category its files do not live in.diff --git a/packages/core/src/repowise/core/generation/kg_reviewer/runner.py b/packages/core/src/repowise/core/generation/kg_reviewer/runner.pyindex f3f644d49..df6f17718 100644--- a/packages/core/src/repowise/core/generation/kg_reviewer/runner.py+++ b/packages/core/src/repowise/core/generation/kg_reviewer/runner.py@@ -20,12 +20,13 @@ from .findings import ReviewReportlogger = structlog.get_logger(__name__)-def _kg_parts(kg: Any) -> tuple[list[dict], list[dict], list[dict]]:- """Extract (nodes, layers, tour) from a KnowledgeGraphResult-like object."""+def _kg_parts(kg: Any) -> tuple[list[dict], list[dict], list[dict], dict]:+ """Extract (nodes, layers, tour, domain_graph) from a KG-like object."""nodes = list(getattr(kg, "nodes", None) or [])layers = list(getattr(kg, "layers", None) or [])tour = list(getattr(kg, "tour", None) or [])- return nodes, layers, tour+ domain_graph = getattr(kg, "domain_graph", None) or {}+ return nodes, layers, tour, domain_graphdef run_review(kg: Any) -> ReviewReport:@@ -34,7 +35,7 @@ def run_review(kg: Any) -> ReviewReport:Pure and side-effect free. *kg* is any object exposing ``nodes``,``layers``, and ``tour`` (the in-memory ``KnowledgeGraphResult``)."""- nodes, layers, tour = _kg_parts(kg)+ nodes, layers, tour, domain_graph = _kg_parts(kg)findings = [*checks.check_summaries_restate_filename(nodes),*checks.check_tour_reasons_distinct(tour),@@ -42,6 +43,13 @@ def run_review(kg: Any) -> ReviewReport:*checks.check_tour_sequential(tour),*checks.check_layer_name_category(layers, nodes),]+ if domain_graph:+ findings += [+ *checks.check_no_orphan_domains(domain_graph),+ *checks.check_flow_has_steps(domain_graph),+ *checks.check_step_maps_to_real_node(domain_graph, nodes),+ *checks.check_step_order_valid(domain_graph),+ ]return ReviewReport(findings=findings)diff --git a/packages/core/src/repowise/core/generation/knowledge_graph.py b/packages/core/src/repowise/core/generation/knowledge_graph.pyindex e42386ed4..cb01bd007 100644--- a/packages/core/src/repowise/core/generation/knowledge_graph.py+++ b/packages/core/src/repowise/core/generation/knowledge_graph.py@@ -51,6 +51,7 @@ async def enrich_knowledge_graph(generated_pages: list[Any] | None = None,progress: Any | None = None,reasoning: str = "auto",+ prior_domain_graph: dict | None = None,) -> Any:"""Enrich deterministic KG with LLM-generated layer names and tour."""enriched_layers = await _enrich_layers(@@ -90,6 +91,14 @@ async def enrich_knowledge_graph(kg_skeleton.layers = enriched_layerskg_skeleton.tour = tour+ # Behavior-oriented domain graph (Domain -> Flow -> Step). Synthesized from+ # the enriched layers + file summaries + import edges (not raw source), with+ # a fixed, bounded LLM budget. Best-effort: a failure leaves the structural+ # KG untouched and the domain graph empty.+ await _synthesize_domain_graph(+ kg_skeleton, llm_client, generated_pages, reasoning, prior_domain_graph+ )+# Post-generation invariant gate: validate the fully-assembled KG (layers,# tour, summaries) against hard invariants and quality signals before it is# persisted. Deterministic, zero-LLM, bounded (no regeneration loop) —@@ -364,6 +373,51 @@ def build_deterministic_tour(return steps+# ---------------------------------------------------------------------------+# Domain graph synthesis+# ---------------------------------------------------------------------------+++def _page_summary_map(generated_pages: list[Any] | None) -> dict[str, str]:+ """target_path -> summary, from generated wiki pages (zero LLM cost)."""+ out: dict[str, str] = {}+ for p in generated_pages or []:+ summary = getattr(p, "summary", None) or ""+ target = getattr(p, "target_path", None) or ""+ if summary and target:+ out[target] = summary+ return out+++async def _synthesize_domain_graph(+ kg_skeleton: Any,+ llm_client: Any,+ generated_pages: list[Any] | None,+ reasoning: str,+ prior_domain_graph: dict | None,+) -> None:+ """Synthesize + attach the domain graph; best-effort, never blocks export."""+ try:+ from repowise.core.generation.domain_graph import (+ DomainGraph,+ synthesize_domain_graph,+ )++ prior = DomainGraph.from_dict(prior_domain_graph) if prior_domain_graph else None+ graph = await synthesize_domain_graph(+ layers=kg_skeleton.layers,+ nodes=kg_skeleton.nodes,+ edges=kg_skeleton.edges,+ llm_client=llm_client,+ page_summaries=_page_summary_map(generated_pages),+ prior=prior,+ reasoning=reasoning,+ )+ kg_skeleton.domain_graph = graph.to_dict() if not graph.is_empty() else {}+ except Exception as exc: # pragma: no cover - defensive, never blocks export+ logger.warning("domain_graph_synthesis_failed", error=str(exc))++# ---------------------------------------------------------------------------# Summary backfill# ---------------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/persistence/crud/__init__.py b/packages/core/src/repowise/core/persistence/crud/__init__.pyindex 950535cf0..2456375d2 100644--- a/packages/core/src/repowise/core/persistence/crud/__init__.py+++ b/packages/core/src/repowise/core/persistence/crud/__init__.py@@ -21,6 +21,7 @@ from __future__ import annotationsfrom .analysis import * # noqa: F403from .chat import * # noqa: F403from .decisions import * # noqa: F403+from .domain_graph import * # noqa: F403from .external_systems import * # noqa: F403from .git import * # noqa: F403from .graph import * # noqa: F403diff --git a/packages/core/src/repowise/core/persistence/crud/domain_graph.py b/packages/core/src/repowise/core/persistence/crud/domain_graph.pynew file mode 100644index 000000000..da51bb2de--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/domain_graph.py@@ -0,0 +1,85 @@+"""CRUD operations for the behavior-oriented domain graph.++Full-replace upserts mirroring the knowledge-graph CRUD (delete-then-insert per+repo), so a re-index writes a clean graph and the call is safe to repeat. Row+shapes are the dicts produced by+``repowise.core.generation.domain_graph.flatten_nodes`` /+``flatten_edges``.+"""++from __future__ import annotations++import json++from sqlalchemy import delete, select+from sqlalchemy.ext.asyncio import AsyncSession++from ..models import DomainGraphEdge, DomainGraphNode+++async def upsert_domain_graph_nodes(+ session: AsyncSession, repo_id: str, nodes: list[dict]+) -> None:+ """Replace all domain-graph nodes for a repo (delete + bulk insert)."""+ await session.execute(+ delete(DomainGraphNode).where(DomainGraphNode.repository_id == repo_id)+ )+ for i, node in enumerate(nodes):+ session.add(+ DomainGraphNode(+ repository_id=repo_id,+ node_id=node["node_id"],+ kind=node["kind"],+ name=node.get("name", ""),+ summary=node.get("summary", ""),+ parent_id=node.get("parent_id"),+ step_order=node.get("step_order"),+ implements_json=json.dumps(node.get("implements", [])),+ display_order=node.get("display_order", i),+ page_title=node.get("page_title", ""),+ page_content=node.get("page_content", ""),+ )+ )+ await session.flush()+++async def upsert_domain_graph_edges(+ session: AsyncSession, repo_id: str, edges: list[dict]+) -> None:+ """Replace all domain-graph edges for a repo (delete + bulk insert)."""+ await session.execute(+ delete(DomainGraphEdge).where(DomainGraphEdge.repository_id == repo_id)+ )+ for edge in edges:+ session.add(+ DomainGraphEdge(+ repository_id=repo_id,+ source_node_id=edge["source_node_id"],+ target_node_id=edge["target_node_id"],+ edge_type=edge["edge_type"],+ weight=float(edge.get("weight", 0.0)),+ )+ )+ await session.flush()+++async def get_domain_graph_nodes(+ session: AsyncSession, repo_id: str+) -> list[DomainGraphNode]:+ """Fetch all domain-graph nodes for a repo, ordered for stable display."""+ result = await session.execute(+ select(DomainGraphNode)+ .where(DomainGraphNode.repository_id == repo_id)+ .order_by(DomainGraphNode.kind, DomainGraphNode.display_order)+ )+ return list(result.scalars())+++async def get_domain_graph_edges(+ session: AsyncSession, repo_id: str+) -> list[DomainGraphEdge]:+ """Fetch all domain-graph edges for a repo."""+ result = await session.execute(+ select(DomainGraphEdge).where(DomainGraphEdge.repository_id == repo_id)+ )+ return list(result.scalars())diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 2d7f4f3e5..232f80b5a 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1105,6 +1105,83 @@ class KnowledgeGraphNodeMeta(Base):__table_args__ = (UniqueConstraint("repository_id", "node_id", name="uq_kg_node_meta"),)+class DomainGraphNode(Base):+ """A node in the behavior-oriented domain graph (Domain / Flow / Step).++ Mirrors the discriminated single-table shape of :class:`GraphNode`: one+ table holds all three levels, distinguished by ``kind``. ``node_id`` is the+ stable synthesized id (``"domain:<slug>"`` / ``"flow:<domain>/<slug>"`` /+ ``"step:<flow>/<n>"``). ``implements_json`` holds a step's real implementing+ file node ids (and a domain's member file node ids); ``parent_id`` links a+ flow to its domain and a step to its flow.++ The renderable wiki page content (markdown) is persisted alongside the+ structural fields on the same row: domain and flow rows carry a+ ``page_title``/``page_content``; step rows leave them empty. This is the+ second persistence representation (graph rows + page content) the surfacing+ phase will embed; no consumer reads it yet.+ """++ __tablename__ = "domain_graph_nodes"++ id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)+ repository_id: Mapped[str] = mapped_column(+ String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False+ )+ node_id: Mapped[str] = mapped_column(Text, nullable=False)+ kind: Mapped[str] = mapped_column(String(16), nullable=False) # domain | flow | step+ name: Mapped[str] = mapped_column(Text, nullable=False, default="")+ summary: Mapped[str] = mapped_column(Text, nullable=False, default="")+ parent_id: Mapped[str | None] = mapped_column(Text, nullable=True)+ step_order: Mapped[int | None] = mapped_column(Integer, nullable=True)+ implements_json: Mapped[str] = mapped_column(Text, nullable=False, default="[]")+ display_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # Renderable wiki page content (markdown) + its title; populated for+ # domain/flow rows, empty for steps.+ page_title: Mapped[str] = mapped_column(Text, nullable=False, default="")+ page_content: Mapped[str] = mapped_column(Text, nullable=False, default="")+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False, default=_now_utc+ )++ __table_args__ = (+ UniqueConstraint("repository_id", "node_id", name="uq_domain_graph_node"),+ )+++class DomainGraphEdge(Base):+ """A typed edge in the domain graph.++ ``edge_type`` is one of ``contains_flow`` (domain->flow), ``flow_step``+ (flow->step, ``weight`` = step order), or ``cross_domain`` (domain->domain,+ ``weight`` = crossing-import count). Mirrors :class:`GraphEdge`'s shape.+ """++ __tablename__ = "domain_graph_edges"++ id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)+ repository_id: Mapped[str] = mapped_column(+ String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False+ )+ source_node_id: Mapped[str] = mapped_column(Text, nullable=False)+ target_node_id: Mapped[str] = mapped_column(Text, nullable=False)+ edge_type: Mapped[str] = mapped_column(String(32), nullable=False)+ weight: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False, default=_now_utc+ )++ __table_args__ = (+ UniqueConstraint(+ "repository_id",+ "source_node_id",+ "target_node_id",+ "edge_type",+ name="uq_domain_graph_edge",+ ),+ )++class PipelineJob(Base):"""Checkpoint/resume state for one execution of a pipeline phase.diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.pyindex aded586ea..1438f468a 100644--- a/packages/core/src/repowise/core/pipeline/orchestrator.py+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py@@ -694,12 +694,17 @@ async def run_pipeline(generated_pages=generated_pages,progress=progress,reasoning=_kg_reasoning,+ # When the KG was reused (fingerprint unchanged) it carries the+ # prior domain graph; pass it so unchanged domains skip the LLM.+ prior_domain_graph=getattr(knowledge_graph_result, "domain_graph", None) or None,)if progress:+ _dg = getattr(knowledge_graph_result, "domain_graph", None) or {}progress.on_message("info",f" ↳ KG enriched: {len(knowledge_graph_result.layers)} layers, "- f"{len(knowledge_graph_result.tour)} tour steps",+ f"{len(knowledge_graph_result.tour)} tour steps, "+ f"{len(_dg.get('domains', []))} domains",)_phase_done(progress, "knowledge_graph.enrich")except (ValueError, KeyError, OSError, RuntimeError) as exc:diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 699c30160..6065ee544 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -645,6 +645,32 @@ async def persist_generation(result: Any, session: Any, repo_id: str) -> None:if file_node_meta:await upsert_kg_node_meta(session, repo_id, file_node_meta)+ # ---- Domain graph (behavior-oriented Domain -> Flow -> Step) --------+ domain_graph = getattr(kg, "domain_graph", None) or {}+ if domain_graph.get("domains"):+ from repowise.core.generation.domain_graph import (+ DomainGraph,+ flatten_edges,+ flatten_nodes,+ )+ from repowise.core.persistence.crud import (+ upsert_domain_graph_edges,+ upsert_domain_graph_nodes,+ )++ graph = DomainGraph.from_dict(domain_graph)+ # Optional hottest-step risk annotation: flag steps touching a churn+ # hotspot, sourced from the per-file git metadata.+ hotspot_node_ids = {+ "file:" + gm.get("file_path", "")+ for gm in (result.git_metadata_list or [])+ if isinstance(gm, dict) and gm.get("is_hotspot") and gm.get("file_path")+ }+ await upsert_domain_graph_nodes(+ session, repo_id, flatten_nodes(graph, hotspot_node_ids)+ )+ await upsert_domain_graph_edges(session, repo_id, flatten_edges(graph))+async def persist_pipeline_result(result: Any,diff --git a/tests/unit/generation/test_domain_graph.py b/tests/unit/generation/test_domain_graph.pynew file mode 100644index 000000000..208cbcd00--- /dev/null+++ b/tests/unit/generation/test_domain_graph.py@@ -0,0 +1,357 @@+"""Tests for the behavior-oriented domain graph (generation.domain_graph).++Pure-logic units (context assembly, parsing + node-id validation, render,+fingerprint cache, persistence mapping) plus the async synthesis orchestrator+driven by a stub LLM - no live LLM, no DB.+"""++from __future__ import annotations++import json+from types import SimpleNamespace++import pytest++from repowise.core.generation.domain_graph import (+ DomainGraph,+ DomainNode,+ FlowNode,+ StepNode,+ cache,+ context,+ flatten_edges,+ flatten_nodes,+ parsing,+ render,+ synthesize_domain_graph,+)+from repowise.core.generation.domain_graph.synthesis import (+ DOMAIN_NAMING_SYSTEM,+)+++def _node(path: str, *, pagerank: float = 0.0, summary: str = "") -> dict:+ return {"id": f"file:{path}", "filePath": path, "pagerank": pagerank, "summary": summary}+++def _layers() -> list[dict]:+ return [+ {"id": "layer:ingestion", "name": "Ingestion", "nodeIds": ["file:a.py", "file:b.py"]},+ {"id": "layer:health", "name": "Health", "nodeIds": ["file:c.py"]},+ {"id": "layer:empty", "name": "Empty", "nodeIds": []},+ ]+++def _nodes() -> list[dict]:+ return [+ _node("a.py", pagerank=0.9, summary="parses files"),+ _node("b.py", pagerank=0.1, summary="walks tree"),+ _node("c.py", pagerank=0.5, summary="scores health"),+ ]+++# ---------------------------------------------------------------------------+# context (a)+# ---------------------------------------------------------------------------+++def test_build_layer_clusters_drops_empty_and_ranks_by_pagerank():+ clusters = context.build_layer_clusters(_layers(), _nodes())+ ids = [c.layer_id for c in clusters]+ assert ids == ["layer:ingestion", "layer:health"] # empty layer dropped+ ingestion = clusters[0]+ assert ingestion.file_count == 2+ assert ingestion.top_files[0] == "a.py" # highest pagerank first+++def test_member_node_ids_union_sorted():+ members = context.member_node_ids(["layer:ingestion", "layer:health"], _layers(), _nodes())+ assert members == ["file:a.py", "file:b.py", "file:c.py"]+++def test_derive_cross_domain_edges_counts_boundary_imports():+ domains = [+ DomainNode(slug="idx", name="Indexing", member_node_ids=["file:a.py", "file:b.py"]),+ DomainNode(slug="hlth", name="Health", member_node_ids=["file:c.py"]),+ ]+ edges = [+ {"source": "file:a.py", "target": "file:c.py"}, # crosses idx -> hlth+ {"source": "file:a.py", "target": "file:b.py"}, # internal to idx+ ]+ cross = context.derive_cross_domain_edges(domains, edges)+ assert len(cross) == 1+ assert (cross[0].source, cross[0].target, cross[0].weight) == ("domain:idx", "domain:hlth", 1)+++def test_heaviest_internal_edges_only_within_members():+ members = {"file:a.py", "file:b.py"}+ edges = [+ {"source": "file:a.py", "target": "file:b.py", "weight": 5},+ {"source": "file:a.py", "target": "file:c.py", "weight": 9}, # leaves member set+ ]+ pairs = context.heaviest_internal_edges(members, edges)+ assert pairs == [("a.py", "b.py")]+++# ---------------------------------------------------------------------------+# parsing + node-id validation (c)+# ---------------------------------------------------------------------------+++def test_parse_domains_rejects_unknown_layers_and_dedupes_claims():+ content = json.dumps(+ {+ "domains": [+ {"slug": "idx", "name": "Indexing", "member_layer_ids": ["layer:ingestion", "layer:bogus"]},+ {"slug": "dup", "name": "Dup", "member_layer_ids": ["layer:ingestion"]}, # already claimed+ {"slug": "hlth", "name": "Health", "member_layer_ids": ["layer:health"]},+ ]+ }+ )+ domains = parsing.parse_domains(content, {"layer:ingestion", "layer:health"})+ slugs = [d.slug for d in domains]+ assert slugs == ["idx", "hlth"] # bogus rejected, dup dropped (no members left)+ assert domains[0].member_layer_ids == ["layer:ingestion"]+++def test_resolve_flows_rejects_hallucinated_node_ids():+ # The key anti-hallucination guarantee: an unknown file path is dropped, and+ # a step left with no real member is removed entirely.+ content = json.dumps(+ {+ "flows": [+ {+ "slug": "ingest",+ "name": "Ingest",+ "steps": [+ {"order": 1, "name": "parse", "implements": ["a.py", "ghost.py"]},+ {"order": 2, "name": "phantom", "implements": ["ghost.py"]},+ ],+ }+ ]+ }+ )+ flows = parsing.resolve_flows(content, {"file:a.py", "file:b.py"})+ assert len(flows) == 1+ steps = flows[0].steps+ assert len(steps) == 1 # phantom step dropped+ assert steps[0].order == 1+ assert steps[0].implements == ["file:a.py"] # ghost.py never survives+ # The hallucinated id appears nowhere in the resolved graph.+ assert all("ghost" not in nid for s in steps for nid in s.implements)+++def test_resolve_flows_renumbers_orders_contiguously():+ content = json.dumps(+ {+ "flows": [+ {+ "slug": "f",+ "name": "F",+ "steps": [+ {"order": 7, "name": "first", "implements": ["a.py"]},+ {"order": 9, "name": "second", "implements": ["b.py"]},+ ],+ }+ ]+ }+ )+ flows = parsing.resolve_flows(content, {"file:a.py", "file:b.py"})+ assert [s.order for s in flows[0].steps] == [1, 2]+++def test_resolve_flows_drops_flow_with_no_valid_steps():+ content = json.dumps(+ {"flows": [{"slug": "f", "name": "F", "steps": [{"order": 1, "implements": ["ghost.py"]}]}]}+ )+ assert parsing.resolve_flows(content, {"file:a.py"}) == []+++def test_parse_json_tolerates_code_fences():+ assert parsing.parse_json('```json\n{"a": 1}\n```') == {"a": 1}+ assert parsing.parse_json("garbage") is None+++# ---------------------------------------------------------------------------+# render+# ---------------------------------------------------------------------------+++def test_render_flow_page_lists_steps_and_marks_hotspots():+ domain = DomainNode(slug="idx", name="Indexing")+ flow = FlowNode(+ slug="ingest",+ name="Ingest",+ steps=[StepNode(order=1, name="parse", implements=["file:a.py", "file:b.py"])],+ )+ title, _summary, md = render.render_flow_page(domain, flow, hotspot_node_ids={"file:a.py"})+ assert title == "Ingest (Indexing)"+ assert "`a.py`" in md and "`b.py`" in md+ assert "hotspot" in md # step touches a hotspot file+++def test_render_domain_page_lists_flows():+ domain = DomainNode(+ slug="idx",+ name="Indexing",+ summary="Builds the index.",+ flows=[FlowNode(slug="ingest", name="Ingest", steps=[StepNode(order=1, name="p", implements=["file:a.py"])])],+ )+ title, _summary, md = render.render_domain_page(domain)+ assert title == "Indexing"+ assert "Ingest" in md+++# ---------------------------------------------------------------------------+# cache+# ---------------------------------------------------------------------------+++def test_domain_fingerprint_changes_with_members_and_summaries():+ fp1 = cache.domain_fingerprint(["file:a.py", "file:b.py"], {"file:a.py": "x", "file:b.py": "y"})+ fp2 = cache.domain_fingerprint(["file:b.py", "file:a.py"], {"file:a.py": "x", "file:b.py": "y"})+ fp3 = cache.domain_fingerprint(["file:a.py", "file:b.py"], {"file:a.py": "CHANGED", "file:b.py": "y"})+ assert fp1 == fp2 # order-independent+ assert fp1 != fp3 # summary change invalidates+++def test_domain_fingerprint_changes_with_internal_coupling():+ members = ["file:a.py", "file:b.py"]+ summaries = {"file:a.py": "x", "file:b.py": "y"}+ base = cache.domain_fingerprint(members, summaries)+ coupled = cache.domain_fingerprint(members, summaries, [("file:a.py", "file:b.py")])+ assert base != coupled # a new internal edge invalidates the cache+++def test_reuse_flows_matches_on_slug_and_fingerprint():+ flows = [FlowNode(slug="f", name="F", steps=[StepNode(order=1, name="s", implements=["file:a.py"])])]+ prior = DomainGraph(domains=[DomainNode(slug="idx", name="Indexing", fingerprint="abc", flows=flows)])+ match = DomainNode(slug="idx", name="Indexing", fingerprint="abc")+ miss = DomainNode(slug="idx", name="Indexing", fingerprint="different")+ assert cache.reuse_flows(prior, match) is not None+ assert cache.reuse_flows(prior, miss) is None+ assert cache.reuse_flows(None, match) is None+++# ---------------------------------------------------------------------------+# persistence mapping (d)+# ---------------------------------------------------------------------------+++def test_flatten_nodes_and_edges_shapes():+ g = DomainGraph(+ domains=[+ DomainNode(+ slug="idx",+ name="Indexing",+ member_node_ids=["file:a.py"],+ flows=[FlowNode(slug="ingest", name="Ingest", steps=[StepNode(order=1, name="parse", implements=["file:a.py"])])],+ )+ ]+ )+ nodes = flatten_nodes(g)+ kinds = [n["kind"] for n in nodes]+ assert kinds == ["domain", "flow", "step"]+ step_row = nodes[2]+ assert step_row["node_id"] == "step:idx/ingest/1"+ assert step_row["parent_id"] == "flow:idx/ingest"+ edges = flatten_edges(g)+ types = {e["edge_type"] for e in edges}+ assert types == {"contains_flow", "flow_step"}+++# ---------------------------------------------------------------------------+# synthesis (async orchestration with a stub LLM)+# ---------------------------------------------------------------------------+++class _StubLLM:+ """Returns canned JSON keyed on whether it's the naming or a flow prompt."""++ def __init__(self, naming: str, flows_by_domain: dict[str, str]):+ self._naming = naming+ self._flows = flows_by_domain+ self.calls = 0++ async def generate(self, system, user, **kwargs):+ self.calls += 1+ if system == DOMAIN_NAMING_SYSTEM:+ return SimpleNamespace(content=self._naming)+ for name, resp in self._flows.items():+ if name in user:+ return SimpleNamespace(content=resp)+ return SimpleNamespace(content='{"flows": []}')+++async def test_synthesize_end_to_end_validates_and_links():+ naming = json.dumps(+ {+ "domains": [+ {"slug": "idx", "name": "Indexing", "member_layer_ids": ["layer:ingestion"]},+ {"slug": "hlth", "name": "Health", "member_layer_ids": ["layer:health"]},+ ]+ }+ )+ flows = {+ "Indexing": json.dumps(+ {"flows": [{"slug": "ingest", "name": "Ingest", "steps": [+ {"order": 1, "name": "parse", "implements": ["a.py", "ghost.py"]}]}]}+ ),+ "Health": json.dumps(+ {"flows": [{"slug": "score", "name": "Score", "steps": [+ {"order": 1, "name": "rate", "implements": ["c.py"]}]}]}+ ),+ }+ llm = _StubLLM(naming, flows)+ edges = [{"source": "file:a.py", "target": "file:c.py"}] # idx -> hlth+ graph = await synthesize_domain_graph(_layers(), _nodes(), edges, llm)++ assert [d.slug for d in graph.domains] == ["idx", "hlth"]+ idx = graph.domains[0]+ assert idx.flows[0].steps[0].implements == ["file:a.py"] # ghost rejected+ assert llm.calls == 3 # 1 naming + 2 flow+ assert len(graph.cross_domain) == 1+ assert (graph.cross_domain[0].source, graph.cross_domain[0].target) == ("domain:idx", "domain:hlth")+++async def test_synthesize_drops_orphan_domains():+ naming = json.dumps(+ {"domains": [+ {"slug": "idx", "name": "Indexing", "member_layer_ids": ["layer:ingestion"]},+ {"slug": "hlth", "name": "Health", "member_layer_ids": ["layer:health"]},+ ]}+ )+ flows = {+ "Indexing": json.dumps({"flows": [{"slug": "ingest", "name": "Ingest", "steps": [+ {"order": 1, "name": "parse", "implements": ["a.py"]}]}]}),+ "Health": '{"flows": []}', # no flows -> Health is an orphan+ }+ graph = await synthesize_domain_graph(_layers(), _nodes(), [], _StubLLM(naming, flows))+ assert [d.slug for d in graph.domains] == ["idx"] # Health dropped+++async def test_synthesize_empty_when_no_clusters():+ graph = await synthesize_domain_graph([], [], [], _StubLLM("{}", {}))+ assert graph.is_empty()+++async def test_synthesize_reuses_cached_domain_without_llm_call():+ naming = json.dumps(+ {"domains": [{"slug": "idx", "name": "Indexing", "member_layer_ids": ["layer:ingestion"]}]}+ )+ # First run to learn the fingerprint + flows.+ flows = {"Indexing": json.dumps({"flows": [{"slug": "ingest", "name": "Ingest", "steps": [+ {"order": 1, "name": "parse", "implements": ["a.py"]}]}]})}+ first = await synthesize_domain_graph(_layers(), _nodes(), [], _StubLLM(naming, flows))+ prior = first++ # Second run with the prior graph: the flow call must be skipped (only the+ # naming call fires) because the member fingerprint is unchanged.+ llm2 = _StubLLM(naming, flows)+ second = await synthesize_domain_graph(_layers(), _nodes(), [], llm2, prior=prior)+ assert llm2.calls == 1 # naming only; flows reused+ assert second.domains[0].flows[0].steps[0].implements == ["file:a.py"]diff --git a/tests/unit/generation/test_kg_reviewer.py b/tests/unit/generation/test_kg_reviewer.pyindex 35d743dde..eebd90998 100644--- a/tests/unit/generation/test_kg_reviewer.py+++ b/tests/unit/generation/test_kg_reviewer.py@@ -199,3 +199,84 @@ def test_apply_review_tags_low_signal_summaries():# Idempotent — re-applying does not duplicate the tag.apply_review(kg)assert nodes[0]["tags"].count("low_signal_summary") == 1+++# ---------------------------------------------------------------------------+# domain-graph invariants+# ---------------------------------------------------------------------------+++def _domain_graph(flows, *, slug="idx", name="Indexing"):+ return {"domains": [{"slug": slug, "name": name, "flows": flows}], "cross_domain": []}+++def _good_step():+ return {"order": 1, "name": "parse", "implements": ["file:a.py"]}+++def test_check_no_orphan_domains_flags_domain_without_flows():+ findings = checks.check_no_orphan_domains(_domain_graph([]))+ assert len(findings) == 1+ assert findings[0].severity is Severity.CRITICAL+ assert findings[0].check == "domain_no_orphan"+++def test_check_flow_has_steps_flags_empty_flow():+ dg = _domain_graph([{"slug": "f", "name": "F", "steps": []}])+ findings = checks.check_flow_has_steps(dg)+ assert len(findings) == 1 and findings[0].severity is Severity.CRITICAL+++def test_check_step_maps_to_real_node_flags_unknown_and_empty():+ nodes = [_node("a.py")]+ dg = _domain_graph([+ {"slug": "f", "name": "F", "steps": [+ {"order": 1, "name": "ok", "implements": ["file:a.py"]},+ {"order": 2, "name": "ghost", "implements": ["file:nope.py"]},+ {"order": 3, "name": "empty", "implements": []},+ ]},+ ])+ findings = checks.check_step_maps_to_real_node(dg, nodes)+ # The valid step produces no finding; the unknown + empty steps each do.+ assert len(findings) == 2+ assert all(f.severity is Severity.CRITICAL for f in findings)+++def test_check_step_order_valid_flags_gap():+ dg = _domain_graph([+ {"slug": "f", "name": "F", "steps": [+ {"order": 1, "implements": ["file:a.py"]},+ {"order": 3, "implements": ["file:a.py"]},+ ]},+ ])+ findings = checks.check_step_order_valid(dg)+ assert len(findings) == 1 and findings[0].severity is Severity.CRITICAL+++def test_run_review_includes_domain_checks_when_present():+ nodes = [_node("a.py", summary="a module.")]+ layers = [{"id": "layer:x", "nodeIds": ["file:a.py"]}]+ kg = SimpleNamespace(+ nodes=nodes,+ layers=layers,+ tour=[],+ domain_graph=_domain_graph([{"slug": "f", "name": "F", "steps": [_good_step()]}]),+ )+ report = run_review(kg)+ assert report.ok # a well-formed domain graph passes+++def test_run_review_flags_bad_domain_graph():+ nodes = [_node("a.py", summary="a module.")]+ layers = [{"id": "layer:x", "nodeIds": ["file:a.py"]}]+ kg = SimpleNamespace(+ nodes=nodes,+ layers=layers,+ tour=[],+ domain_graph=_domain_graph([{"slug": "f", "name": "F", "steps": [+ {"order": 1, "name": "ghost", "implements": ["file:hallucinated.py"]},+ ]}]),+ )+ report = run_review(kg)+ assert not report.ok+ assert any(f.check == "step_maps_to_real_node" for f in report.criticals)diff --git a/tests/unit/persistence/test_models.py b/tests/unit/persistence/test_models.pyindex e13db2c55..8460875cb 100644--- a/tests/unit/persistence/test_models.py+++ b/tests/unit/persistence/test_models.py@@ -323,5 +323,7 @@ def test_base_includes_all_models():"knowledge_graph_tour_steps","kg_project_meta","kg_node_meta",+ "domain_graph_nodes",+ "domain_graph_edges",}assert expected == table_names