Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
similarity index 85%
rename from packages/core/alembic/versions/0032_health_dimensions.py
rename to packages/core/alembic/versions/0033_health_dimensions.py
index 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 recompute
repopulates them. The overall surfaced score is unchanged.
-Revision ID: 0032
-Revises: 0031
+Revision ID: 0033
+Revises: 0032
Create 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 sa
from 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 = None
depends_on: str | Sequence[str] | None = None
diff --git a/packages/core/alembic/versions/0034_domain_graph.py b/packages/core/alembic/versions/0034_domain_graph.py
new file mode 100644
index 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.py
index 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_graph
return 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/packages/core/src/repowise/core/generation/domain_graph/context.py b/packages/core/src/repowise/core/generation/domain_graph/context.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 flows
diff --git a/packages/core/src/repowise/core/generation/domain_graph/persistence_map.py b/packages/core/src/repowise/core/generation/domain_graph/persistence_map.py
new file mode 100644
index 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 rows
diff --git a/packages/core/src/repowise/core/generation/domain_graph/prompts.py b/packages/core/src/repowise/core/generation/domain_graph/prompts.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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 ReviewReport
logger = 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_graph
def 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.py
index 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_layers
kg_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__.py
index 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 annotations
from .analysis import * # noqa: F403
from .chat import * # noqa: F403
from .decisions import * # noqa: F403
+from .domain_graph import * # noqa: F403
from .external_systems import * # noqa: F403
from .git import * # noqa: F403
from .graph import * # noqa: F403
diff --git a/packages/core/src/repowise/core/persistence/crud/domain_graph.py b/packages/core/src/repowise/core/persistence/crud/domain_graph.py
new file mode 100644
index 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.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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