@swarmvaultai/engine 0.1.23 → 0.1.24

package/dist/index.js

@@ -192,6 +192,9 @@ function graphPageById(graph) {
 function graphNodeById(graph) {
   return new Map(graph.nodes.map((node) => [node.id, node]));
 }
+function exportHyperedgeNodeId(hyperedge) {
+  return `hyperedge:${hyperedge.id}`;
+}
 function sortedCommunities(graph) {
   const known = (graph.communities ?? []).map((community) => ({
     ...community,
@@ -356,6 +359,11 @@ function renderGraphMl(graph) {
     { id: "n_community", for: "node", name: "communityId", type: "string" },
     { id: "n_degree", for: "node", name: "degree", type: "double" },
     { id: "n_bridge", for: "node", name: "bridgeScore", type: "double" },
+    { id: "n_relation", for: "node", name: "relation", type: "string" },
+    { id: "n_evidence", for: "node", name: "evidenceClass", type: "string" },
+    { id: "n_confidence", for: "node", name: "confidence", type: "double" },
+    { id: "n_source_pages", for: "node", name: "sourcePageIds", type: "string" },
+    { id: "n_why", for: "node", name: "why", type: "string" },
     { id: "e_relation", for: "edge", name: "relation", type: "string" },
     { id: "e_status", for: "edge", name: "status", type: "string" },
     { id: "e_evidence", for: "edge", name: "evidenceClass", type: "string" },
@@ -394,6 +402,21 @@ function renderGraphMl(graph) {
     }
     lines.push("    </node>");
   }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    lines.push(`    <node id="${xmlEscape(exportHyperedgeNodeId(hyperedge))}">`);
+    for (const [key, value] of [
+      ["n_label", hyperedge.label],
+      ["n_type", "hyperedge"],
+      ["n_relation", hyperedge.relation],
+      ["n_evidence", hyperedge.evidenceClass],
+      ["n_confidence", hyperedge.confidence],
+      ["n_source_pages", hyperedge.sourcePageIds],
+      ["n_why", hyperedge.why]
+    ]) {
+      lines.push(`      <data key="${key}">${xmlEscape(graphMlData(value))}</data>`);
+    }
+    lines.push("    </node>");
+  }
   for (const edge of [...graph.edges].sort((left, right) => left.id.localeCompare(right.id))) {
     lines.push(`    <edge id="${xmlEscape(edge.id)}" source="${xmlEscape(edge.source)}" target="${xmlEscape(edge.target)}">`);
     for (const [key, value] of [
@@ -407,6 +430,23 @@ function renderGraphMl(graph) {
     }
     lines.push("    </edge>");
   }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    for (const nodeId of hyperedge.nodeIds) {
+      lines.push(
+        `    <edge id="${xmlEscape(`member:${hyperedge.id}:${nodeId}`)}" source="${xmlEscape(exportHyperedgeNodeId(hyperedge))}" target="${xmlEscape(nodeId)}">`
+      );
+      for (const [key, value] of [
+        ["e_relation", "group_member"],
+        ["e_status", "inferred"],
+        ["e_evidence", hyperedge.evidenceClass],
+        ["e_confidence", hyperedge.confidence],
+        ["e_provenance", hyperedge.sourcePageIds]
+      ]) {
+        lines.push(`      <data key="${key}">${xmlEscape(graphMlData(value))}</data>`);
+      }
+      lines.push("    </edge>");
+    }
+  }
   lines.push("  </graph>", "</graphml>", "");
   return lines.join("\n");
 }
@@ -433,13 +473,41 @@ function renderCypher(graph) {
     lines.push(`MERGE (n:SwarmNode {id: '${cypherEscape(node.id)}'}) SET n += { ${props} };`);
   }
   lines.push("");
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
+    lines.push(
+      `MERGE (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}) SET h += { id: '${cypherEscape(hyperedgeNodeId)}', label: '${cypherEscape(
+        hyperedge.label
+      )}', type: 'hyperedge', relation: '${cypherEscape(hyperedge.relation)}', evidenceClass: '${cypherEscape(
+        hyperedge.evidenceClass
+      )}', confidence: ${hyperedge.confidence}, sourcePageIds: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}', why: '${cypherEscape(
+        hyperedge.why
+      )}' };`
+    );
+  }
+  if ((graph.hyperedges ?? []).length) {
+    lines.push("");
+  }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
+    for (const nodeId of hyperedge.nodeIds) {
+      lines.push(
+        `MATCH (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}), (n:SwarmNode {id: '${cypherEscape(nodeId)}'})`,
+        `MERGE (h)-[r:GROUP_MEMBER {id: '${cypherEscape(`member:${hyperedge.id}:${nodeId}`)}'}]->(n)`,
+        `SET r += { relation: 'group_member', status: 'inferred', evidenceClass: '${cypherEscape(
+          hyperedge.evidenceClass
+        )}', confidence: ${hyperedge.confidence}, provenance: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}' };`
+      );
+    }
+  }
+  lines.push("");
   for (const edge of [...graph.edges].sort((left, right) => left.id.localeCompare(right.id))) {
     lines.push(
       `MATCH (a:SwarmNode {id: '${cypherEscape(edge.source)}'}), (b:SwarmNode {id: '${cypherEscape(edge.target)}'})`,
       `MERGE (a)-[r:${relationType(edge.relation)} {id: '${cypherEscape(edge.id)}'}]->(b)`,
       `SET r += { relation: '${cypherEscape(edge.relation)}', status: '${cypherEscape(edge.status)}', evidenceClass: '${cypherEscape(
         edge.evidenceClass
-      )}', confidence: ${edge.confidence}, provenance: '${cypherEscape(JSON.stringify(edge.provenance))}' };`
+      )}', confidence: ${edge.confidence}, provenance: '${cypherEscape(JSON.stringify(edge.provenance))}'${edge.similarityReasons?.length ? `, similarityReasons: '${cypherEscape(JSON.stringify(edge.similarityReasons))}'` : ""} };`
     );
   }
   lines.push("");
@@ -5910,6 +5978,331 @@ async function runDeepLint(rootDir, structuralFindings, options = {}) {
   );
 }
 
+// src/graph-enrichment.ts
+var STOPWORDS2 = /* @__PURE__ */ new Set([
+  "about",
+  "after",
+  "also",
+  "among",
+  "and",
+  "around",
+  "because",
+  "been",
+  "being",
+  "between",
+  "both",
+  "does",
+  "from",
+  "into",
+  "just",
+  "like",
+  "many",
+  "more",
+  "most",
+  "much",
+  "note",
+  "only",
+  "other",
+  "over",
+  "same",
+  "such",
+  "than",
+  "that",
+  "their",
+  "them",
+  "there",
+  "these",
+  "this",
+  "through",
+  "under",
+  "very",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "with",
+  "would",
+  "your"
+]);
+function normalizeValue(value) {
+  return normalizeWhitespace(value).toLowerCase();
+}
+function addFeature(bucket, reason, value) {
+  if (!value) {
+    return;
+  }
+  const normalized = normalizeValue(value);
+  if (!normalized) {
+    return;
+  }
+  if (!bucket.has(reason)) {
+    bucket.set(reason, /* @__PURE__ */ new Set());
+  }
+  bucket.get(reason)?.add(normalized);
+}
+function themeTokens(value) {
+  return uniqueBy(
+    normalizeValue(value).split(/[^a-z0-9]+/i).filter((token) => token.length >= 4 && !STOPWORDS2.has(token)),
+    (token) => token
+  ).slice(0, 6);
+}
+function pairKey(left, right) {
+  return [left, right].sort((a, b) => a.localeCompare(b)).join("|");
+}
+function hasDistinctScope(left, right) {
+  if (left.pageId && right.pageId && left.pageId !== right.pageId) {
+    return true;
+  }
+  const leftSources = new Set(left.sourceIds);
+  const rightSources = new Set(right.sourceIds);
+  const leftOnly = [...leftSources].some((sourceId) => !rightSources.has(sourceId));
+  const rightOnly = [...rightSources].some((sourceId) => !leftSources.has(sourceId));
+  return leftOnly || rightOnly;
+}
+function supportCount(values) {
+  return values?.size ?? 0;
+}
+function similarityScore(reasons) {
+  const concept = supportCount(reasons.get("shared_concept"));
+  const entity = supportCount(reasons.get("shared_entity"));
+  const symbol = supportCount(reasons.get("shared_symbol"));
+  const rationale = supportCount(reasons.get("shared_rationale_theme"));
+  const sourceType = supportCount(reasons.get("shared_source_type"));
+  const tag = supportCount(reasons.get("shared_tag"));
+  const categoryCount = [...reasons.keys()].length;
+  const weighted = (concept ? 0.46 + Math.min(0.12, (concept - 1) * 0.04) : 0) + (entity ? 0.34 + Math.min(0.1, (entity - 1) * 0.03) : 0) + (symbol ? 0.24 + Math.min(0.08, (symbol - 1) * 0.02) : 0) + (rationale ? 0.18 + Math.min(0.08, (rationale - 1) * 0.03) : 0) + (sourceType ? 0.1 : 0) + (tag ? 0.12 + Math.min(0.04, (tag - 1) * 0.02) : 0);
+  const categoryBonus = categoryCount >= 3 ? 0.08 : categoryCount === 2 ? 0.04 : 0;
+  return Math.min(0.96, weighted + categoryBonus);
+}
+function describeSimilarityReasons(reasons) {
+  if (!reasons?.length) {
+    return "This link is inferred from multiple shared graph features.";
+  }
+  const labels = reasons.map(
+    (reason) => reason === "shared_concept" ? "shared concepts" : reason === "shared_entity" ? "shared entities" : reason === "shared_symbol" ? "shared symbols" : reason === "shared_rationale_theme" ? "shared rationale themes" : reason === "shared_source_type" ? "shared source type" : "shared tags"
+  );
+  return `This link is inferred from ${labels.join(", ")}.`;
+}
+function nodeContexts(nodes, manifests, analyses) {
+  const manifestsBySourceId = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
+  const analysesBySourceId = new Map(analyses.map((analysis) => [analysis.sourceId, analysis]));
+  return nodes.filter((node) => node.type !== "symbol" && node.type !== "concept" && node.type !== "entity").map((node) => {
+    const features = /* @__PURE__ */ new Map();
+    if (node.type === "source" || node.type === "module") {
+      for (const sourceId of node.sourceIds) {
+        const analysis = analysesBySourceId.get(sourceId);
+        const manifest = manifestsBySourceId.get(sourceId);
+        if (!analysis) {
+          continue;
+        }
+        for (const concept of analysis.concepts) {
+          addFeature(features, "shared_concept", concept.name);
+        }
+        for (const entity of analysis.entities) {
+          addFeature(features, "shared_entity", entity.name);
+        }
+        if (manifest?.sourceType) {
+          addFeature(features, "shared_source_type", manifest.sourceType);
+        }
+        if (analysis.code) {
+          const exportedSymbols = analysis.code.symbols.filter((symbol) => symbol.exported);
+          for (const symbol of (exportedSymbols.length ? exportedSymbols : analysis.code.symbols).slice(0, 12)) {
+            addFeature(features, "shared_symbol", symbol.name);
+          }
+        }
+        for (const rationale of analysis.rationales) {
+          for (const token of themeTokens(rationale.text)) {
+            addFeature(features, "shared_rationale_theme", token);
+          }
+        }
+      }
+    } else if (node.type === "rationale") {
+      for (const sourceId of node.sourceIds) {
+        const analysis = analysesBySourceId.get(sourceId);
+        const manifest = manifestsBySourceId.get(sourceId);
+        if (manifest?.sourceType) {
+          addFeature(features, "shared_source_type", manifest.sourceType);
+        }
+        const rationale = analysis?.rationales.find((item) => item.id === node.id);
+        for (const token of themeTokens(rationale?.text ?? node.label)) {
+          addFeature(features, "shared_rationale_theme", token);
+        }
+      }
+    }
+    return { node, featureValues: features };
+  }).filter((context) => context.featureValues.size > 0);
+}
+function buildSemanticSimilarityEdges(nodes, edges, manifests, analyses) {
+  const contexts = nodeContexts(nodes, manifests, analyses);
+  const contextsById = new Map(contexts.map((context) => [context.node.id, context]));
+  const directPairs = new Set(edges.map((edge) => pairKey(edge.source, edge.target)));
+  const pairReasons = /* @__PURE__ */ new Map();
+  for (const reason of ["shared_concept", "shared_entity", "shared_symbol", "shared_rationale_theme", "shared_source_type"]) {
+    const buckets = /* @__PURE__ */ new Map();
+    for (const context of contexts) {
+      for (const value of context.featureValues.get(reason) ?? []) {
+        const bucketId = `${context.node.type}:${reason}:${value}`;
+        if (!buckets.has(bucketId)) {
+          buckets.set(bucketId, []);
+        }
+        buckets.get(bucketId)?.push(context.node.id);
+      }
+    }
+    for (const [bucketId, nodeIds] of buckets.entries()) {
+      if (nodeIds.length < 2) {
+        continue;
+      }
+      const value = bucketId.slice(bucketId.indexOf(`${reason}:`) + `${reason}:`.length);
+      const uniqueNodeIds = uniqueBy(nodeIds, (nodeId) => nodeId).sort((left, right) => left.localeCompare(right));
+      for (let index = 0; index < uniqueNodeIds.length; index++) {
+        const left = contextsById.get(uniqueNodeIds[index]);
+        if (!left) {
+          continue;
+        }
+        for (let cursor = index + 1; cursor < uniqueNodeIds.length; cursor++) {
+          const right = contextsById.get(uniqueNodeIds[cursor]);
+          if (!right || !hasDistinctScope(left.node, right.node)) {
+            continue;
+          }
+          const key = pairKey(left.node.id, right.node.id);
+          if (directPairs.has(key)) {
+            continue;
+          }
+          if (!pairReasons.has(key)) {
+            pairReasons.set(key, /* @__PURE__ */ new Map());
+          }
+          if (!pairReasons.get(key)?.has(reason)) {
+            pairReasons.get(key)?.set(reason, /* @__PURE__ */ new Set());
+          }
+          pairReasons.get(key)?.get(reason)?.add(value);
+        }
+      }
+    }
+  }
+  return [...pairReasons.entries()].flatMap(([key, reasons]) => {
+    const [leftId, rightId] = key.split("|");
+    const left = contextsById.get(leftId)?.node;
+    const right = contextsById.get(rightId)?.node;
+    if (!left || !right) {
+      return [];
+    }
+    const confidence = similarityScore(reasons);
+    if (confidence < 0.5) {
+      return [];
+    }
+    return [
+      {
+        id: `similar:${sha256(`${left.id}|${right.id}|${[...reasons.keys()].sort().join(",")}`).slice(0, 16)}`,
+        source: left.id,
+        target: right.id,
+        relation: "semantically_similar_to",
+        status: "inferred",
+        evidenceClass: "inferred",
+        confidence,
+        provenance: uniqueBy(
+          [...left.sourceIds, ...right.sourceIds].sort((a, b) => a.localeCompare(b)),
+          (value) => value
+        ),
+        similarityReasons: [...reasons.keys()].sort((a, b) => a.localeCompare(b))
+      }
+    ];
+  }).sort((left, right) => right.confidence - left.confidence || left.id.localeCompare(right.id));
+}
+function buildTopicHyperedges(graph) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const connectedSources = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    if (edge.relation !== "mentions" || edge.evidenceClass !== "extracted") {
+      continue;
+    }
+    const sourceNode = nodesById.get(edge.source);
+    const targetNode = nodesById.get(edge.target);
+    if (sourceNode?.type !== "source" || !(targetNode?.type === "concept" || targetNode?.type === "entity")) {
+      continue;
+    }
+    if (!connectedSources.has(targetNode.id)) {
+      connectedSources.set(targetNode.id, []);
+    }
+    connectedSources.get(targetNode.id)?.push(sourceNode.id);
+  }
+  return [...connectedSources.entries()].flatMap(([anchorId, members]) => {
+    const anchor = nodesById.get(anchorId);
+    const uniqueMembers = uniqueBy(members, (member) => member).sort((left, right) => left.localeCompare(right));
+    if (!anchor || uniqueMembers.length < 3) {
+      return [];
+    }
+    const nodeIds = [anchor.id, ...uniqueMembers];
+    const sourcePageIds = uniqueBy(nodeIds.map((nodeId) => nodesById.get(nodeId)?.pageId ?? "").filter(Boolean), (value) => value);
+    return [
+      {
+        id: `hyper:${sha256(`participate_in|${anchor.id}|${uniqueMembers.join("|")}`).slice(0, 16)}`,
+        label: anchor.label,
+        relation: "participate_in",
+        nodeIds,
+        evidenceClass: "extracted",
+        confidence: Math.min(0.96, 0.72 + uniqueMembers.length * 0.06),
+        sourcePageIds,
+        why: `${uniqueMembers.length} source nodes converge on ${anchor.label} through extracted mention edges.`
+      }
+    ];
+  });
+}
+function buildModuleFormHyperedges(graph) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const definedSymbols = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    if (edge.relation !== "defines" || edge.evidenceClass !== "extracted") {
+      continue;
+    }
+    const moduleNode = nodesById.get(edge.source);
+    const symbolNode = nodesById.get(edge.target);
+    if (moduleNode?.type !== "module" || symbolNode?.type !== "symbol") {
+      continue;
+    }
+    if (!definedSymbols.has(moduleNode.id)) {
+      definedSymbols.set(moduleNode.id, []);
+    }
+    definedSymbols.get(moduleNode.id)?.push(symbolNode.id);
+  }
+  return [...definedSymbols.entries()].flatMap(([moduleId, members]) => {
+    const moduleNode = nodesById.get(moduleId);
+    const uniqueMembers = uniqueBy(members, (member) => member).sort((left, right) => left.localeCompare(right));
+    if (!moduleNode || uniqueMembers.length < 3) {
+      return [];
+    }
+    const nodeIds = [moduleNode.id, ...uniqueMembers];
+    const sourcePageIds = uniqueBy(nodeIds.map((nodeId) => nodesById.get(nodeId)?.pageId ?? "").filter(Boolean), (value) => value);
+    return [
+      {
+        id: `hyper:${sha256(`form|${moduleNode.id}|${uniqueMembers.join("|")}`).slice(0, 16)}`,
+        label: `${moduleNode.label} API`,
+        relation: "form",
+        nodeIds,
+        evidenceClass: "extracted",
+        confidence: Math.min(0.98, 0.78 + uniqueMembers.length * 0.04),
+        sourcePageIds,
+        why: `${moduleNode.label} and ${uniqueMembers.length} defined symbols form one local module surface.`
+      }
+    ];
+  });
+}
+function enrichGraph(graph, manifests, analyses) {
+  const similarityEdges = buildSemanticSimilarityEdges(graph.nodes, graph.edges, manifests, analyses);
+  const enrichedEdges = [...graph.edges, ...similarityEdges].sort((left, right) => left.id.localeCompare(right.id));
+  const hyperedges = uniqueBy(
+    [
+      ...buildTopicHyperedges({ ...graph, edges: enrichedEdges, hyperedges: [] }),
+      ...buildModuleFormHyperedges({ ...graph, edges: enrichedEdges, hyperedges: [] })
+    ].sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)),
+    (hyperedge) => hyperedge.id
+  );
+  return {
+    edges: enrichedEdges,
+    hyperedges
+  };
+}
+
 // src/graph-tools.ts
 function normalizeTarget(value) {
   return normalizeWhitespace(value).toLowerCase();
@@ -5920,6 +6313,9 @@ function nodeById(graph) {
 function pageById(graph) {
   return new Map(graph.pages.map((page) => [page.id, page]));
 }
+function hyperedgesForNode(graph, nodeId) {
+  return (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.nodeIds.includes(nodeId)).sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label));
+}
 function scoreMatch(query, candidate) {
   const normalizedQuery = normalizeTarget(query);
   const normalizedCandidate = normalizeTarget(candidate);
@@ -5968,6 +6364,14 @@ function nodeMatches(graph, query) {
     score: Math.max(scoreMatch(query, node.label), scoreMatch(query, node.id))
   })).filter((match) => match.score > 0).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label));
 }
+function hyperedgeMatches(graph, query) {
+  return (graph.hyperedges ?? []).map((hyperedge) => ({
+    type: "hyperedge",
+    id: hyperedge.id,
+    label: hyperedge.label,
+    score: Math.max(scoreMatch(query, hyperedge.label), scoreMatch(query, hyperedge.why), scoreMatch(query, hyperedge.relation))
+  })).filter((match) => match.score > 0).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label));
+}
 function graphAdjacency(graph) {
   const adjacency = /* @__PURE__ */ new Map();
   const push = (nodeId, item) => {
@@ -6016,14 +6420,15 @@ function queryGraph(graph, question, searchResults, options) {
   const traversal = options?.traversal ?? "bfs";
   const budget = Math.max(3, Math.min(options?.budget ?? 12, 50));
   const matches = uniqueBy(
-    [...pageSearchMatches(graph, question, searchResults), ...nodeMatches(graph, question)],
+    [...pageSearchMatches(graph, question, searchResults), ...nodeMatches(graph, question), ...hyperedgeMatches(graph, question)],
     (match) => `${match.type}:${match.id}`
   ).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label)).slice(0, 12);
   const pages = pageById(graph);
   const seeds = uniqueBy(
     [
       ...searchResults.flatMap((result) => pages.get(result.pageId)?.nodeIds ?? []),
-      ...matches.filter((match) => match.type === "node").map((match) => match.id)
+      ...matches.filter((match) => match.type === "node").map((match) => match.id),
+      ...matches.filter((match) => match.type === "hyperedge").flatMap((match) => graph.hyperedges.find((hyperedge) => hyperedge.id === match.id)?.nodeIds ?? [])
     ],
     (item) => item
   ).filter(Boolean);
@@ -6064,6 +6469,10 @@ function queryGraph(graph, question, searchResults, options) {
     visitedNodeIds.map((nodeId) => nodes.get(nodeId)?.communityId).filter((communityId) => Boolean(communityId)),
     (item) => item
   );
+  const hyperedgeIds = uniqueBy(
+    (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.nodeIds.some((nodeId) => visitedNodeIds.includes(nodeId))).map((hyperedge) => hyperedge.id),
+    (item) => item
+  );
   return {
     question,
     traversal,
@@ -6074,6 +6483,7 @@ function queryGraph(graph, question, searchResults, options) {
     ),
     visitedNodeIds,
     visitedEdgeIds: [...visitedEdgeIds],
+    hyperedgeIds,
     pageIds,
     communities,
     matches,
@@ -6081,6 +6491,7 @@ function queryGraph(graph, question, searchResults, options) {
       `Seeds: ${seeds.join(", ") || "none"}`,
       `Visited nodes: ${visitedNodeIds.length}`,
       `Visited edges: ${visitedEdgeIds.size}`,
+      `Touched group patterns: ${hyperedgeIds.length}`,
       `Communities: ${communities.join(", ") || "none"}`,
       `Pages: ${pageIds.join(", ") || "none"}`
     ].join("\n")
@@ -6200,11 +6611,13 @@ function explainGraphTarget(graph, target) {
     page,
     community: communityLabel(graph, node.communityId),
     neighbors,
+    hyperedges: hyperedgesForNode(graph, node.id),
     summary: [
       `Node: ${node.label}`,
       `Type: ${node.type}`,
       `Community: ${node.communityId ?? "none"}`,
       `Neighbors: ${neighbors.length}`,
+      `Group patterns: ${hyperedgesForNode(graph, node.id).length}`,
       `Page: ${page?.path ?? "none"}`
     ].join("\n")
   };
@@ -6212,6 +6625,20 @@ function explainGraphTarget(graph, target) {
 function topGodNodes(graph, limit = 10) {
   return graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, limit);
 }
+function listHyperedges(graph, target, limit = 25) {
+  if (!target) {
+    return [...graph.hyperedges ?? []].sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)).slice(0, limit);
+  }
+  const node = resolveNode(graph, target);
+  if (node) {
+    return hyperedgesForNode(graph, node.id).slice(0, limit);
+  }
+  const page = graph.pages.find((candidate) => normalizeTarget(candidate.path) === normalizeTarget(target) || candidate.id === target);
+  if (!page) {
+    return [];
+  }
+  return (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.sourcePageIds.includes(page.id) || page.nodeIds.some((nodeId) => hyperedge.nodeIds.includes(nodeId))).sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)).slice(0, limit);
+}
 
 // src/markdown.ts
 import matter5 from "gray-matter";
@@ -6712,13 +7139,120 @@ function nodeSummary(node) {
   const bridge = typeof node.bridgeScore === "number" ? `bridge=${node.bridgeScore}` : "";
   return [node.type, degree, bridge].filter(Boolean).join(", ");
 }
-function crossCommunityEdges(graph) {
+function sourceTypeForNode(node, pagesById) {
+  if (!node?.pageId) {
+    return void 0;
+  }
+  return pagesById.get(node.pageId)?.sourceType;
+}
+function supportingPathDetails(graph, edge) {
+  const path23 = shortestGraphPath(graph, edge.source, edge.target);
+  const edgesById = new Map(graph.edges.map((item) => [item.id, item]));
+  const pathEdges = path23.edgeIds.map((edgeId) => edgesById.get(edgeId)).filter((item) => Boolean(item));
+  return {
+    pathNodeIds: path23.nodeIds,
+    pathEdgeIds: path23.edgeIds,
+    pathRelations: pathEdges.map((item) => item.relation),
+    pathEvidenceClasses: pathEdges.map((item) => item.evidenceClass),
+    pathSummary: path23.summary
+  };
+}
+function surpriseScore(edge, graph, pagesById, hyperedgesByNodeId) {
   const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
-  return graph.edges.filter((edge) => {
-    const source = nodesById.get(edge.source);
-    const target = nodesById.get(edge.target);
-    return source?.communityId && target?.communityId && source.communityId !== target.communityId;
-  }).sort((left, right) => right.confidence - left.confidence || left.relation.localeCompare(right.relation));
+  const source = nodesById.get(edge.source);
+  const target = nodesById.get(edge.target);
+  const reasons = [];
+  let score = edge.confidence * 0.45;
+  if (source?.communityId && target?.communityId && source.communityId !== target.communityId) {
+    score += 0.18;
+    reasons.push(`it crosses communities ${source.communityId} and ${target.communityId}`);
+  }
+  if (source?.pageId && target?.pageId && source.pageId !== target.pageId) {
+    score += 0.12;
+    reasons.push("it spans different canonical pages");
+  }
+  if (source?.type && target?.type && source.type !== target.type) {
+    score += 0.08;
+    reasons.push(`it bridges ${source.type} and ${target.type} nodes`);
+  }
+  const sourceType = sourceTypeForNode(source, pagesById);
+  const targetType = sourceTypeForNode(target, pagesById);
+  if (sourceType && targetType && sourceType !== targetType) {
+    score += 0.07;
+    reasons.push(`it crosses source types (${sourceType} and ${targetType})`);
+  }
+  if ((source?.bridgeScore ?? 0) > 0 || (target?.bridgeScore ?? 0) > 0) {
+    score += 0.08;
+    reasons.push("a bridge node is involved");
+  }
+  if (edge.relation === "semantically_similar_to") {
+    score += 0.12;
+    reasons.push(describeSimilarityReasons(edge.similarityReasons));
+  }
+  if (edge.evidenceClass === "ambiguous") {
+    score += 0.08;
+    reasons.push("the supporting evidence is ambiguous");
+  }
+  const overlappingHyperedges = (hyperedgesByNodeId.get(edge.source) ?? []).filter((hyperedge) => hyperedge.nodeIds.includes(edge.target));
+  if (overlappingHyperedges.length) {
+    score += 0.06;
+    reasons.push(`it also appears in ${overlappingHyperedges.length} group pattern${overlappingHyperedges.length === 1 ? "" : "s"}`);
+  }
+  const why = normalizeWhitespace(reasons.join("; ")) || "it links graph regions that are otherwise weakly connected";
+  const explanation = normalizeWhitespace(`${source?.label ?? edge.source} connects to ${target?.label ?? edge.target} because ${why}.`);
+  return { score: Math.min(0.99, score), why, explanation };
+}
+function topSurprisingConnections(graph, pagesById) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const hyperedgesByNodeId = /* @__PURE__ */ new Map();
+  for (const hyperedge of graph.hyperedges ?? []) {
+    for (const nodeId of hyperedge.nodeIds) {
+      if (!hyperedgesByNodeId.has(nodeId)) {
+        hyperedgesByNodeId.set(nodeId, []);
+      }
+      hyperedgesByNodeId.get(nodeId)?.push(hyperedge);
+    }
+  }
+  return uniqueBy(
+    graph.edges.filter((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      return Boolean(
+        source?.communityId && target?.communityId && source.communityId !== target.communityId || edge.relation === "semantically_similar_to" || edge.evidenceClass === "ambiguous" || source?.type && target?.type && source.type !== target.type
+      );
+    }).map((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      const path23 = supportingPathDetails(graph, edge);
+      const scored = surpriseScore(edge, graph, pagesById, hyperedgesByNodeId);
+      return {
+        id: edge.id,
+        sourceNodeId: edge.source,
+        sourceLabel: source?.label ?? edge.source,
+        targetNodeId: edge.target,
+        targetLabel: target?.label ?? edge.target,
+        relation: edge.relation,
+        evidenceClass: edge.evidenceClass,
+        confidence: edge.confidence,
+        pathNodeIds: path23.pathNodeIds,
+        pathEdgeIds: path23.pathEdgeIds,
+        pathRelations: path23.pathRelations,
+        pathEvidenceClasses: path23.pathEvidenceClasses,
+        pathSummary: path23.pathSummary,
+        why: scored.why,
+        explanation: scored.explanation,
+        surpriseScore: scored.score
+      };
+    }).sort(
+      (left, right) => right.surpriseScore - left.surpriseScore || right.confidence - left.confidence || left.id.localeCompare(right.id)
+    ).slice(0, 8),
+    (connection) => connection.id
+  ).map(({ surpriseScore: _surpriseScore, ...connection }) => connection);
+}
+function topGroupPatterns(graph) {
+  return [...graph.hyperedges ?? []].sort(
+    (left, right) => right.confidence - left.confidence || right.nodeIds.length - left.nodeIds.length || left.label.localeCompare(right.label)
+  ).slice(0, 8);
 }
 function suggestedGraphQuestions(graph) {
   const thinCommunities = (graph.communities ?? []).filter((community) => community.nodeIds.length <= 2);
@@ -6729,7 +7263,7 @@ function suggestedGraphQuestions(graph) {
   ]).slice(0, 6);
 }
 function buildGraphReportArtifact(input) {
-  const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
+  const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
   const godNodes = input.graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, 8);
   const bridgeNodes = input.graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 8);
   const thinCommunities = (input.graph.communities ?? []).filter((community) => community.nodeIds.length <= 2).map((community) => {
@@ -6743,33 +7277,8 @@ function buildGraphReportArtifact(input) {
       title: page?.title
     };
   });
-  const surprisingConnections = crossCommunityEdges(input.graph).slice(0, 8).map((edge) => {
-    const source = nodesById.get(edge.source);
-    const target = nodesById.get(edge.target);
-    const path23 = shortestGraphPath(input.graph, edge.source, edge.target);
-    const sourceCommunity = source?.communityId ? input.graph.communities?.find((community) => community.id === source.communityId) : void 0;
-    const targetCommunity = target?.communityId ? input.graph.communities?.find((community) => community.id === target.communityId) : void 0;
-    return {
-      id: edge.id,
-      sourceNodeId: edge.source,
-      sourceLabel: source?.label ?? edge.source,
-      targetNodeId: edge.target,
-      targetLabel: target?.label ?? edge.target,
-      relation: edge.relation,
-      evidenceClass: edge.evidenceClass,
-      confidence: edge.confidence,
-      pathNodeIds: path23.nodeIds,
-      pathEdgeIds: path23.edgeIds,
-      pathSummary: path23.summary,
-      explanation: normalizeWhitespace(
-        [
-          `${source?.label ?? edge.source} links ${sourceCommunity?.label ? `from ${sourceCommunity.label}` : ""}`.trim(),
-          `to ${target?.label ?? edge.target}${targetCommunity?.label ? ` in ${targetCommunity.label}` : ""}`.trim(),
-          `through ${edge.relation} with ${edge.evidenceClass} evidence at ${edge.confidence.toFixed(2)} confidence.`
-        ].join(" ")
-      )
-    };
-  });
+  const surprisingConnections = topSurprisingConnections(input.graph, pagesById);
+  const groupPatterns = topGroupPatterns(input.graph);
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     graphHash: input.graphHash,
@@ -6801,6 +7310,7 @@ function buildGraphReportArtifact(input) {
     })),
     thinCommunities,
     surprisingConnections,
+    groupPatterns,
     suggestedQuestions: suggestedGraphQuestions(input.graph),
     communityPages: input.communityPages.map((page) => ({
       id: page.id,
@@ -6823,13 +7333,20 @@ function buildGraphReportPage(input) {
   const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
   const relatedNodeIds = uniqueStrings2([
     ...input.report.godNodes.map((node) => node.nodeId),
-    ...input.report.bridgeNodes.map((node) => node.nodeId)
+    ...input.report.bridgeNodes.map((node) => node.nodeId),
+    ...input.report.surprisingConnections.flatMap((connection) => [
+      connection.sourceNodeId,
+      connection.targetNodeId,
+      ...connection.pathNodeIds
+    ]),
+    ...input.report.groupPatterns.flatMap((hyperedge) => hyperedge.nodeIds)
   ]);
   const relatedPageIds = uniqueStrings2([
     ...input.report.godNodes.map((node) => node.pageId ?? ""),
     ...input.report.bridgeNodes.map((node) => node.pageId ?? ""),
     ...input.report.communityPages.map((page) => page.id),
-    ...input.report.recentResearchSources.map((page) => page.pageId)
+    ...input.report.recentResearchSources.map((page) => page.pageId),
+    ...input.report.groupPatterns.flatMap((hyperedge) => hyperedge.sourcePageIds)
   ]);
   const relatedSourceIds = uniqueStrings2([
     ...relatedNodeIds.flatMap((nodeId) => nodesById.get(nodeId)?.sourceIds ?? []),
@@ -6910,9 +7427,16 @@ function buildGraphReportPage(input) {
       const target = nodesById.get(connection.targetNodeId);
       const sourceLabel = source ? graphNodeLink(source, pagesById) : `\`${connection.sourceNodeId}\``;
       const targetLabel = target ? graphNodeLink(target, pagesById) : `\`${connection.targetNodeId}\``;
-      return `- ${sourceLabel} ${connection.relation} ${targetLabel} (${connection.evidenceClass}, ${connection.confidence.toFixed(2)}). ${connection.explanation} Path: ${connection.pathSummary}.`;
+      return `- ${sourceLabel} ${connection.relation} ${targetLabel} (${connection.evidenceClass}, ${connection.confidence.toFixed(2)}). Why: ${connection.why}. ${connection.explanation} Path: ${connection.pathSummary}.`;
     }) : ["- No cross-community links detected."],
     "",
+    "## Group Patterns",
+    "",
+    ...input.report.groupPatterns.length ? input.report.groupPatterns.map((hyperedge) => {
+      const linkedNodes = hyperedge.nodeIds.map((nodeId) => nodesById.get(nodeId)).filter((node) => Boolean(node)).map((node) => graphNodeLink(node, pagesById)).join(", ");
+      return `- ${hyperedge.label} (${hyperedge.relation}, ${hyperedge.evidenceClass}, ${hyperedge.confidence.toFixed(2)}). ${hyperedge.why} Members: ${linkedNodes}.`;
+    }) : ["- No multi-node group patterns detected."],
+    "",
     "## New Research Sources",
     "",
     ...input.report.recentResearchSources.length ? input.report.recentResearchSources.map(
@@ -9045,11 +9569,24 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
     ...conceptMap.values(),
     ...entityMap.values()
   ];
-  const metrics = deriveGraphMetrics(graphNodes, edges);
+  const enriched = enrichGraph(
+    {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      nodes: graphNodes,
+      edges,
+      communities: [],
+      sources: manifests,
+      pages
+    },
+    manifests,
+    analyses
+  );
+  const metrics = deriveGraphMetrics(graphNodes, enriched.edges);
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: metrics.nodes,
-    edges,
+    edges: enriched.edges,
+    hyperedges: enriched.hyperedges,
     communities: metrics.communities,
     sources: manifests,
     pages
@@ -9937,6 +10474,7 @@ async function stageOutputApprovalBundle(rootDir, stagedPages) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: previousGraph?.nodes ?? [],
     edges: previousGraph?.edges ?? [],
+    hyperedges: previousGraph?.hyperedges ?? [],
     sources: previousGraph?.sources ?? [],
     pages: nextPages
   };
@@ -10245,6 +10783,7 @@ async function acceptApproval(rootDir, approvalId, targets = []) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: currentGraph?.nodes ?? bundleGraph?.nodes ?? [],
     edges: currentGraph?.edges ?? bundleGraph?.edges ?? [],
+    hyperedges: currentGraph?.hyperedges ?? bundleGraph?.hyperedges ?? [],
     sources: currentGraph?.sources ?? bundleGraph?.sources ?? [],
     pages: sortGraphPages(nextPages)
   };
@@ -10345,6 +10884,7 @@ async function promoteCandidate(rootDir, target) {
     generatedAt: nextUpdatedAt,
     nodes: graph?.nodes ?? [],
     edges: graph?.edges ?? [],
+    hyperedges: graph?.hyperedges ?? [],
     sources: graph?.sources ?? [],
     pages: nextPages
   };
@@ -10386,6 +10926,7 @@ async function archiveCandidate(rootDir, target) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: graph?.nodes ?? [],
     edges: graph?.edges ?? [],
+    hyperedges: graph?.hyperedges ?? [],
     sources: graph?.sources ?? [],
     pages: nextPages
   };
@@ -11226,6 +11767,14 @@ async function explainGraphVault(rootDir, target) {
   const graph = await ensureCompiledGraph(rootDir);
   return explainGraphTarget(graph, target);
 }
+async function listGraphHyperedges(rootDir, target, limit = 25) {
+  const graph = await ensureCompiledGraph(rootDir);
+  return listHyperedges(graph, target, limit);
+}
+async function readGraphReport(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  return readJsonFile(path18.join(paths.wikiDir, "graph", "report.json"));
+}
 async function listGodNodes(rootDir, limit = 10) {
   const graph = await ensureCompiledGraph(rootDir);
   return topGodNodes(graph, limit);
@@ -11389,7 +11938,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.1.22";
+var SERVER_VERSION = "0.1.24";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -11467,10 +12016,19 @@ async function createMcpServer(rootDir) {
       return asToolText(result);
     }
   );
+  server.registerTool(
+    "graph_report",
+    {
+      description: "Return the machine-readable graph report and trust artifact."
+    },
+    async () => {
+      return asToolText(await readGraphReport(rootDir) ?? { error: "Graph report not found. Run `swarmvault compile` first." });
+    }
+  );
   server.registerTool(
     "get_node",
     {
-      description: "Explain a graph node, its page, community, and neighbors.",
+      description: "Explain a graph node, its page, community, neighbors, and group patterns.",
       inputSchema: {
         target: z8.string().min(1).describe("Node or page label/id")
       }
@@ -11479,6 +12037,19 @@ async function createMcpServer(rootDir) {
       return asToolText(await explainGraphVault(rootDir, target));
     }
   );
+  server.registerTool(
+    "get_hyperedges",
+    {
+      description: "List graph hyperedges, optionally filtered to a node or page target.",
+      inputSchema: {
+        target: z8.string().optional().describe("Optional node/page label or id to filter by"),
+        limit: z8.number().int().min(1).max(50).optional().describe("Maximum hyperedges to return")
+      }
+    },
+    async ({ target, limit }) => {
+      return asToolText(await listGraphHyperedges(rootDir, target, limit ?? 25));
+    }
+  );
   server.registerTool(
     "get_neighbors",
     {
@@ -12755,6 +13326,7 @@ export {
   listApprovals,
   listCandidates,
   listGodNodes,
+  listGraphHyperedges,
   listManifests,
   listPages,
   listSchedules,
@@ -12768,6 +13340,7 @@ export {
   queryVault,
   readApproval,
   readExtractedText,
+  readGraphReport,
   readPage,
   rejectApproval,
   resolvePaths,