deepdebug-local-agent 1.0.23 → 1.1.0

package/tools/graphify-validation/config/questions.json

@@ -0,0 +1,31 @@
+{
+  "_comment": "Reference questions with hand-checked ground truth (files that implement the thing asked). kind=symbolic names a symbol; kind=conceptual does not. `keywords` feed only the lexical (ripgrep) baseline. Add or extend per repo; truth paths are validated against the snapshot on every run.",
+  "vh-api-gateway": [
+    {"id": "gw-1", "kind": "symbolic", "question": "Where is the PolicyGate that decides ALLOW, DENY or REQUIRE_HUMAN for an action?", "keywords": ["PolicyGate", "decide"], "truth": ["src/main/java/io/visionhammer/gateway/governance/domain/PolicyGate.java"]},
+    {"id": "gw-2", "kind": "symbolic", "question": "Which class checks that a tenant owns a workspace before allowing access (TenantAccessGuard)?", "keywords": ["TenantAccessGuard", "requireOwnedWorkspace"], "truth": ["src/main/java/io/visionhammer/gateway/security/TenantAccessGuard.java"]},
+    {"id": "gw-3", "kind": "conceptual", "question": "Which code erases a tenant's data when a deletion request is made?", "keywords": ["erasure", "erase", "tenant"], "truth": ["src/main/java/io/visionhammer/gateway/tenancy/application/DataErasureService.java"]},
+    {"id": "gw-4", "kind": "conceptual", "question": "How are login attempts rate limited on the authentication endpoints?", "keywords": ["ratelimit", "RateLimiter", "login", "attempts"], "truth": ["src/main/java/io/visionhammer/gateway/identity/application/AuthRateLimiter.java", "src/main/java/io/visionhammer/gateway/identity/api/AuthPathRateLimitFilter.java"]},
+    {"id": "gw-5", "kind": "conceptual", "question": "Where does the gateway send transactional email through the Resend provider?", "keywords": ["Resend", "email", "send"], "truth": ["src/main/java/io/visionhammer/gateway/shared/mail/ResendEmailSender.java"]},
+    {"id": "gw-6", "kind": "conceptual", "question": "Where are incoming Slack requests verified with a signature before being processed?", "keywords": ["Slack", "signature", "verify"], "truth": ["src/main/java/io/visionhammer/gateway/security/SlackRequestVerifier.java"]},
+    {"id": "gw-7", "kind": "conceptual", "question": "Which component blocks outbound requests to internal or private addresses?", "keywords": ["egress", "private", "internal", "address"], "truth": ["src/main/java/io/visionhammer/gateway/security/EgressUrlGuard.java"]},
+    {"id": "gw-8", "kind": "conceptual", "question": "How are in-band error frames of the agent loop mapped to server-sent events?", "keywords": ["SSE", "frame", "ServerSentEvent", "error"], "truth": ["src/main/java/io/visionhammer/gateway/agenttask/api/SseFrameMapper.java"]}
+  ],
+  "visionhammer-agents": [
+    {"id": "ag-1", "kind": "symbolic", "question": "Which class assembles the RAG context (chunks and files) for an agent2 request (ContextAssembler)?", "keywords": ["ContextAssembler", "chunks"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/service/ContextAssembler.java"]},
+    {"id": "ag-2", "kind": "conceptual", "question": "Where are text embeddings requested from the Voyage API?", "keywords": ["Voyage", "embedding", "embed"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/client/VoyageEmbeddingClient.java"]},
+    {"id": "ag-3", "kind": "conceptual", "question": "Which code masks personal data before scan content leaves the service?", "keywords": ["PII", "mask", "egress"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/scan/PiiEgressMasker.java"]},
+    {"id": "ag-4", "kind": "conceptual", "question": "Where are secrets redacted from the scan report text?", "keywords": ["secret", "mask", "report", "redact"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/scan/report/SecretMasker.java"]},
+    {"id": "ag-5", "kind": "conceptual", "question": "Which detector checks whether application logs carry a correlation id?", "keywords": ["correlation", "detector"], "truth": ["shared/src/main/java/io/visionhammer/agents/shared/scan/CorrelationIdDetector.java"]},
+    {"id": "ag-6", "kind": "conceptual", "question": "Which adapter sends chat completions through the LiteLLM proxy?", "keywords": ["LiteLlm", "chat", "completion"], "truth": ["shared/src/main/java/io/visionhammer/agents/shared/llm/LiteLlmChatAdapter.java"]},
+    {"id": "ag-7", "kind": "conceptual", "question": "Which controller exposes the evaluation of retrieval quality for the RAG index?", "keywords": ["RagEval", "eval", "recall"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/controller/RagEvalController.java"]},
+    {"id": "ag-8", "kind": "conceptual", "question": "Where are stored RAG chunks masked again after they were indexed?", "keywords": ["remask", "chunk", "mask"], "truth": ["agents/software-engineer/src/main/java/io/visionhammer/agents/agent2/rag/remask/application/ChunkRemaskService.java"]}
+  ],
+  "deepdebug-local-agent": [
+    {"id": "la-1", "kind": "conceptual", "question": "Where are commands sent by the platform verified with an Ed25519 signature?", "keywords": ["Ed25519", "signature", "verify"], "truth": ["src/utils/request-signing.js"]},
+    {"id": "la-2", "kind": "conceptual", "question": "Which code removes secret environment variables before running a command for the model?", "keywords": ["secret", "env", "child"], "truth": ["src/utils/child-env.js"]},
+    {"id": "la-3", "kind": "conceptual", "question": "Where does the agent decide whether a shell command is allowed to execute?", "keywords": ["allowlist", "exec", "policy", "command"], "truth": ["src/utils/exec-policy.js"]},
+    {"id": "la-4", "kind": "conceptual", "question": "Which modules confine file paths to the workspace root?", "keywords": ["workspace", "root", "confine", "sandbox"], "truth": ["src/utils/workspace-root.js", "src/utils/sandbox.js"]},
+    {"id": "la-5", "kind": "conceptual", "question": "Which module collapses a storm of identical errors into one forward before reporting to the gateway?", "keywords": ["burst", "suppress", "storm"], "truth": ["src/siblings/burst-suppressor.js"]},
+    {"id": "la-6", "kind": "conceptual", "question": "Where is the network interface the HTTP server listens on chosen?", "keywords": ["bind", "host", "loopback"], "truth": ["src/utils/bind-host.js"]}
+  ]
+}

package/tools/graphify-validation/config/repos.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Only VisionHammer-owned repos. The harness refuses any repo whose origin is not under the VISIONHAMMER GitHub org. Never point it at a customer repository.",
+  "allowed_origin_owners": ["VISIONHAMMER"],
+  "repos": [
+    {"name": "vh-api-gateway", "ref": "origin/release/qa", "lang": "java"},
+    {"name": "visionhammer-agents", "ref": "origin/release/qa", "lang": "java"},
+    {"name": "deepdebug-local-agent", "ref": "origin/main", "lang": "javascript"}
+  ]
+}

package/tools/graphify-validation/config/symbols.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "Symbols for the `affected` versus ripgrep comparison (classes/types for Java, exported functions or classes for JS).",
+  "vh-api-gateway": ["TenantAccessGuard", "PolicyGate", "EgressUrlGuard", "SlackRequestVerifier", "JwtTokenProvider", "AuthRateLimiter", "DataErasureService", "EmailService"],
+  "visionhammer-agents": ["ContextAssembler", "VoyageEmbeddingClient", "PiiEgressMasker", "SecretMasker", "CorrelationIdDetector", "LiteLlmChatAdapter", "PolicyGateGuard", "ChunkRemaskService"],
+  "deepdebug-local-agent": ["confineToRoot", "sanitizedChildEnv", "verifySignature", "evaluateCommand", "resolveBindHost", "validateHeaderRoot", "BurstSuppressor", "isSecretEnvName"]
+}

package/tools/graphify-validation/fixtures/spring/expected.json

@@ -0,0 +1,34 @@
+{
+  "description": "Expected Spring/DI relationships for the synthetic fixture. Selectors are 'File.java::label'. Kinds: edge (direct graph edge, any listed relation), reaches (reverse traversal from `to` reaches `from` within `depth` hops, any relation).",
+  "groups": {
+    "interface_impl": [
+      {"id": "stripe-implements", "kind": "edge", "from": "StripeGateway.java::StripeGateway", "to": "PaymentGateway.java::PaymentGateway", "relations": ["implements", "inherits", "extends"]},
+      {"id": "paypal-implements", "kind": "edge", "from": "PaypalGateway.java::PaypalGateway", "to": "PaymentGateway.java::PaymentGateway", "relations": ["implements", "inherits", "extends"]},
+      {"id": "inmemory-implements", "kind": "edge", "from": "InMemoryCache.java::InMemoryCache", "to": "Cache.java::Cache", "relations": ["implements", "inherits", "extends"]},
+      {"id": "checkout-calls-iface", "kind": "edge", "from": "CheckoutService.java::.checkout()", "to": "PaymentGateway.java::.charge()", "relations": ["calls"]},
+      {"id": "refund-calls-iface-lombok", "kind": "edge", "from": "RefundService.java::.refund()", "to": "PaymentGateway.java::.charge()", "relations": ["calls"]},
+      {"id": "checkout-reaches-stripe-impl", "kind": "reaches", "from": "CheckoutService.java::.checkout()", "to": "StripeGateway.java::.charge()", "depth": 2},
+      {"id": "refund-reaches-paypal-impl", "kind": "reaches", "from": "RefundService.java::.refund()", "to": "PaypalGateway.java::.charge()", "depth": 2},
+      {"id": "refund-reaches-stripe-impl", "kind": "reaches", "from": "RefundService.java::.refund()", "to": "StripeGateway.java::.charge()", "depth": 2}
+    ],
+    "lombok_injection": [
+      {"id": "refund-field-type", "kind": "edge", "from": "RefundService.java::RefundService", "to": "PaymentGateway.java::PaymentGateway", "relations": ["references"]},
+      {"id": "order-field-checkout", "kind": "edge", "from": "OrderController.java::OrderController", "to": "CheckoutService.java::CheckoutService", "relations": ["references"]},
+      {"id": "order-calls-checkout", "kind": "edge", "from": "OrderController.java::.order()", "to": "CheckoutService.java::.checkout()", "relations": ["calls"]},
+      {"id": "order-calls-refund", "kind": "edge", "from": "OrderController.java::.refund()", "to": "RefundService.java::.refund()", "relations": ["calls"]}
+    ],
+    "bean_methods": [
+      {"id": "bean-clock-consumed-by-audit-bean", "kind": "reaches", "from": "AppConfig.java::.auditLogger()", "to": "AppConfig.java::.clock()", "depth": 2},
+      {"id": "bean-audit-built-in-config", "kind": "edge", "from": "AppConfig.java::.auditLogger()", "to": "AuditLogger.java::AuditLogger", "relations": ["calls", "references"]},
+      {"id": "bean-fastcache-impl", "kind": "edge", "from": "AppConfig.java::.fastCache()", "to": "InMemoryCache.java::InMemoryCache", "relations": ["calls", "references"]},
+      {"id": "bean-consumer-checkout-audit", "kind": "reaches", "from": "CheckoutService.java::CheckoutService", "to": "AppConfig.java::.auditLogger()", "depth": 2}
+    ],
+    "qualifier": [
+      {"id": "qualifier-stripe-selected", "kind": "reaches", "from": "CheckoutService.java::CheckoutService", "to": "StripeGateway.java::StripeGateway", "depth": 2},
+      {"id": "qualifier-stripe-not-paypal", "kind": "not_reaches", "requires": "qualifier-stripe-selected", "from": "CheckoutService.java::CheckoutService", "to": "PaypalGateway.java::PaypalGateway", "depth": 2},
+      {"id": "qualifier-fastcache-bean", "kind": "reaches", "from": "CheckoutService.java::CheckoutService", "to": "AppConfig.java::.fastCache()", "depth": 2}
+    ]
+  },
+  "headline_group": "interface_impl",
+  "threshold_pct": 90
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/AppConfig.java

@@ -0,0 +1,29 @@
+package com.example.fx;
+
+import java.time.Clock;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class AppConfig {
+
+    @Bean
+    public Clock clock() {
+        return Clock.systemUTC();
+    }
+
+    @Bean
+    public AuditLogger auditLogger(Clock clock) {
+        return new AuditLogger(clock);
+    }
+
+    @Bean("fastCache")
+    public Cache fastCache() {
+        return new InMemoryCache();
+    }
+
+    @Bean("slowCache")
+    public Cache slowCache() {
+        return new InMemoryCache();
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/AuditLogger.java

@@ -0,0 +1,15 @@
+package com.example.fx;
+
+import java.time.Clock;
+
+public class AuditLogger {
+    private final Clock clock;
+
+    public AuditLogger(Clock clock) {
+        this.clock = clock;
+    }
+
+    public String stamp(String message) {
+        return clock.instant() + " " + message;
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/Cache.java

@@ -0,0 +1,7 @@
+package com.example.fx;
+
+public interface Cache {
+    String get(String key);
+
+    void put(String key, String value);
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/CheckoutService.java

@@ -0,0 +1,25 @@
+package com.example.fx;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.stereotype.Service;
+
+@Service
+public class CheckoutService {
+    private final PaymentGateway gateway;
+    private final Cache cache;
+    private final AuditLogger audit;
+
+    public CheckoutService(@Qualifier("stripe") PaymentGateway gateway,
+                           @Qualifier("fastCache") Cache cache,
+                           AuditLogger audit) {
+        this.gateway = gateway;
+        this.cache = cache;
+        this.audit = audit;
+    }
+
+    public String checkout(String account, long cents) {
+        String receipt = gateway.charge(account, cents);
+        cache.put(account, receipt);
+        return audit.stamp(receipt);
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/InMemoryCache.java

@@ -0,0 +1,18 @@
+package com.example.fx;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class InMemoryCache implements Cache {
+    private final Map<String, String> data = new HashMap<>();
+
+    @Override
+    public String get(String key) {
+        return data.get(key);
+    }
+
+    @Override
+    public void put(String key, String value) {
+        data.put(key, value);
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/OrderController.java

@@ -0,0 +1,22 @@
+package com.example.fx;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequiredArgsConstructor
+public class OrderController {
+    private final CheckoutService checkout;
+    private final RefundService refunds;
+
+    @PostMapping("/orders")
+    public String order(String account, long cents) {
+        return checkout.checkout(account, cents);
+    }
+
+    @PostMapping("/refunds")
+    public String refund(String account, long cents) {
+        return refunds.refund(account, cents);
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/PaymentGateway.java

@@ -0,0 +1,5 @@
+package com.example.fx;
+
+public interface PaymentGateway {
+    String charge(String account, long cents);
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/PaypalGateway.java

@@ -0,0 +1,11 @@
+package com.example.fx;
+
+import org.springframework.stereotype.Component;
+
+@Component("paypal")
+public class PaypalGateway implements PaymentGateway {
+    @Override
+    public String charge(String account, long cents) {
+        return "paypal:" + account + ":" + cents;
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/RefundService.java

@@ -0,0 +1,14 @@
+package com.example.fx;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+@Service
+@RequiredArgsConstructor
+public class RefundService {
+    private final PaymentGateway gateway;
+
+    public String refund(String account, long cents) {
+        return gateway.charge(account, -cents);
+    }
+}

package/tools/graphify-validation/fixtures/spring/src/main/java/com/example/fx/StripeGateway.java

@@ -0,0 +1,11 @@
+package com.example.fx;
+
+import org.springframework.stereotype.Component;
+
+@Component("stripe")
+public class StripeGateway implements PaymentGateway {
+    @Override
+    public String charge(String account, long cents) {
+        return "stripe:" + account + ":" + cents;
+    }
+}

package/tools/graphify-validation/lib/affected_vs_rg.py

@@ -0,0 +1,81 @@
+"""`graphify affected` (depth 1) versus a ripgrep whole-word search (G5, "who calls / who is affected")."""
+from __future__ import annotations
+
+import re
+import subprocess
+
+from gv_common import CODE_EXTS, files_with_word, is_test_path
+
+LINE = re.compile(r"^- (?P<label>.+?) \[(?P<rel>[^\]]+)\] (?P<path>[^:\s]+):L\d+")
+
+
+def parse_affected(text):
+    """Code files only: markdown/doc nodes that mention a symbol are not callers."""
+    files = set()
+    for ln in text.splitlines():
+        m = LINE.match(ln.strip())
+        if m and any(m.group("path").endswith(e) for e in CODE_EXTS):
+            files.add(m.group("path"))
+    return files
+
+
+def run_affected(graphify, workdir, symbol, env, depth=1):
+    last = None
+    for label in (symbol, symbol + "()"):
+        res = subprocess.run([graphify, "affected", label, "--depth", str(depth)], cwd=str(workdir), env=env,
+                             capture_output=True, text=True, timeout=300)
+        last = res
+        if res.returncode == 0 and "- " in res.stdout:
+            return "ok", label, parse_affected(res.stdout)
+        if res.returncode == 3:
+            return "ambiguous", label, set()
+    return "no_match(exit=%s)" % (last.returncode if last else "?"), symbol, set()
+
+
+def definition_files(g, symbol):
+    cands = {symbol, symbol + "()", "." + symbol + "()"}
+    return {n["source_file"] for n in g["nodes"] if n.get("label") in cands and n.get("source_file")
+            and n["label"] != n["source_file"].rsplit("/", 1)[-1]}
+
+
+def compare(graphify, workdir, g, symbols, env):
+    rows = []
+    for sym in symbols:
+        status, used_label, graph_files = run_affected(graphify, workdir, sym, env)
+        _, _, graph_files_d2 = run_affected(graphify, workdir, sym, env, depth=2)
+        defs = definition_files(g, sym)
+        rg_files = files_with_word(workdir, sym, include_tests=True) - defs
+        graph_files = graph_files - defs
+        graph_files_d2 = graph_files_d2 - defs
+        row = {"symbol": sym, "graph_status": status, "definition_files": sorted(defs)}
+        for scope, keep in (("all", lambda f: True), ("main", lambda f: not is_test_path(f))):
+            gf = {f for f in graph_files if keep(f)}
+            rf = {f for f in rg_files if keep(f)}
+            inter = gf & rf
+            g2f = {f for f in graph_files_d2 if keep(f)}
+            row[scope + "_depth2"] = {"graph": len(g2f), "both": len(g2f & rf),
+                                       "recall_vs_rg_pct": round(100.0 * len(g2f & rf) / len(rf), 1) if rf else None}
+            row[scope] = {
+                "graph": len(gf), "rg": len(rf), "both": len(inter),
+                "graph_only": len(gf - rf), "rg_only": len(rf - gf),
+                "recall_vs_rg_pct": round(100.0 * len(inter) / len(rf), 1) if rf else None,
+                "precision_vs_rg_pct": round(100.0 * len(inter) / len(gf), 1) if gf else None,
+                "rg_only_examples": sorted(rf - gf)[:3], "graph_only_examples": sorted(gf - rf)[:3],
+            }
+        rows.append(row)
+    ok = [r for r in rows if r["graph_status"] == "ok" and r["main"]["rg"]]
+    tot_both = sum(r["main"]["both"] for r in ok)
+    tot_rg = sum(r["main"]["rg"] for r in ok)
+    tot_graph = sum(r["main"]["graph"] for r in ok)
+    tot_both2 = sum(r["main_depth2"]["both"] for r in ok)
+    return {
+        "symbols": rows,
+        "aggregate_main": {
+            "symbols_compared": len(ok),
+            "recall_vs_rg_pct": round(100.0 * tot_both / tot_rg, 1) if tot_rg else None,
+            "precision_vs_rg_pct": round(100.0 * tot_both / tot_graph, 1) if tot_graph else None,
+            "depth2_recall_vs_rg_pct": round(100.0 * tot_both2 / tot_rg, 1) if tot_rg else None,
+        },
+        "note": "rg whole-word match is the reference set (includes comments/strings/imports of same-named types); "
+                "graph_only files are references the textual search missed or aliases.",
+    }

package/tools/graphify-validation/lib/audit_hook/sitecustomize.py

@@ -0,0 +1,22 @@
+"""Audit hook loaded via PYTHONPATH (G7). Appends one line per socket/exec event.
+
+Enabled only when GV_AUDIT_FILE is set. The hook is inherited by worker
+processes because PYTHONPATH travels in the environment. It never sends data
+anywhere: it only appends to the local file named by GV_AUDIT_FILE.
+"""
+import os
+import sys
+
+_path = os.environ.get("GV_AUDIT_FILE")
+if _path:
+    _prefixes = ("socket.", "subprocess.Popen", "os.system", "os.exec", "os.posix_spawn", "os.spawn", "ssl.")
+
+    def _hook(event, args):
+        if event.startswith(_prefixes):
+            try:
+                with open(_path, "a", encoding="utf-8") as fh:
+                    fh.write("%d\t%s\t%s\n" % (os.getpid(), event, repr(args)[:300].replace("\n", " ")))
+            except Exception:
+                pass
+
+    sys.addaudithook(_hook)

package/tools/graphify-validation/lib/graph_metrics.py

@@ -0,0 +1,96 @@
+"""Graph-level metrics from graphify-out/graph.json (G1, G2, G8)."""
+from __future__ import annotations
+
+import hashlib
+import os
+from collections import Counter
+from pathlib import Path
+
+from gv_common import iter_code_files, is_test_path, load_json
+
+
+def load_graph(workdir):
+    return load_json(Path(workdir) / "graphify-out" / "graph.json")
+
+
+def edges_of(g):
+    return g.get("links") or g.get("edges") or []
+
+
+def file_node_labels(g):
+    """Set of (source_file) that have at least one real symbol (non file-level node)."""
+    with_symbols = set()
+    all_files = set()
+    for n in g["nodes"]:
+        sf = n.get("source_file")
+        if not sf:
+            continue
+        all_files.add(sf)
+        if n.get("label") != os.path.basename(sf):
+            with_symbols.add(sf)
+    return with_symbols, all_files
+
+
+def g1_extraction(g, workdir):
+    code_files = iter_code_files(workdir)
+    with_symbols, _ = file_node_labels(g)
+    missing = [f for f in code_files if f not in with_symbols]
+    n = len(code_files)
+    return {
+        "code_files": n,
+        "files_with_symbols": n - len(missing),
+        "coverage_pct": round(100.0 * (n - len(missing)) / n, 2) if n else None,
+        "files_without_symbols": missing[:200],
+        "files_without_symbols_total": len(missing),
+        "of_which_in_tests": sum(1 for f in missing if is_test_path(f)),
+    }
+
+
+def g2_edges(g):
+    es = edges_of(g)
+    conf = Counter(e.get("confidence") for e in es)
+    total = len(es)
+    main = [e for e in es if not is_test_path(e.get("source_file", ""))]
+    main_inf = sum(1 for e in main if e.get("confidence") == "INFERRED")
+    inferred_calls = Counter()
+    for e in es:
+        if e.get("confidence") == "INFERRED":
+            inferred_calls[e.get("relation")] += 1
+    return {
+        "nodes": len(g["nodes"]),
+        "edges": total,
+        "extracted": conf.get("EXTRACTED", 0),
+        "inferred": conf.get("INFERRED", 0),
+        "inferred_pct": round(100.0 * conf.get("INFERRED", 0) / total, 2) if total else None,
+        "edges_from_main_sources": len(main),
+        "inferred_pct_main_sources": round(100.0 * main_inf / len(main), 2) if main else None,
+        "inferred_by_relation": dict(inferred_calls.most_common(6)),
+        "communities": len({n.get("community") for n in g["nodes"] if n.get("community") is not None}),
+        "cross_repo_edges": 0,
+        "cross_repo_note": "one graph per repo by construction; a mixed corpus is not built by this harness",
+    }
+
+
+def signature(g):
+    """Order-independent fingerprint of nodes and edges (communities excluded)."""
+    node_ids = sorted(n["id"] for n in g["nodes"])
+    edge_keys = sorted("%s|%s|%s|%s" % (e["source"], e["target"], e.get("relation"), e.get("confidence")) for e in edges_of(g))
+    h = hashlib.sha256()
+    h.update("\n".join(node_ids).encode())
+    h.update(b"\x00")
+    h.update("\n".join(edge_keys).encode())
+    return {"nodes": len(node_ids), "edges": len(edge_keys), "sha256": h.hexdigest()[:16]}
+
+
+def class_index(g):
+    """Helpers shared by the edge oracle and the Spring fixture check."""
+    ns = {n["id"]: n for n in g["nodes"]}
+    owner = {}
+    for e in edges_of(g):
+        if e.get("relation") == "method":
+            owner[e["target"]] = e["source"]
+    supers = {}
+    for e in edges_of(g):
+        if e.get("relation") in ("inherits", "implements", "extends"):
+            supers.setdefault(ns[e["source"]]["label"], set()).add(ns[e["target"]]["label"])
+    return ns, owner, supers

package/tools/graphify-validation/lib/gv_common.py

@@ -0,0 +1,130 @@
+"""Shared helpers for the Graphify validation harness (stdlib only, Python >= 3.9)."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+HARNESS_DIR = Path(__file__).resolve().parent.parent
+
+# Extensions that count as "code" for G1 (pom/SQL/markdown are excluded on purpose).
+CODE_EXTS = {
+    ".java", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".tf",
+}
+SKIP_DIRS = {
+    ".git", "node_modules", "target", "graphify-out", "dist", "build", ".idea",
+    ".gradle", "__pycache__", ".venv", "venv",
+}
+TEST_MARKERS = ("/src/test/", "/test/", "/tests/", "/__tests__/", "/fixtures/")
+TEST_SUFFIXES = (".test.js", ".test.ts", ".test.tsx", ".spec.ts", ".spec.js", "Test.java", "Tests.java", "IT.java")
+
+
+def load_json(path):
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def dump_json(path, obj):
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(obj, fh, indent=2, sort_keys=True, ensure_ascii=False)
+        fh.write("\n")
+
+
+def is_test_path(rel):
+    p = "/" + rel.replace("\\", "/")
+    return any(m in p for m in TEST_MARKERS) or p.endswith(TEST_SUFFIXES)
+
+
+def iter_code_files(root):
+    """Yield repo-relative paths of code files under root (sorted, deterministic)."""
+    root = Path(root)
+    out = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
+        for fn in sorted(filenames):
+            if Path(fn).suffix in CODE_EXTS:
+                out.append(str((Path(dirpath) / fn).relative_to(root)).replace(os.sep, "/"))
+    return out
+
+
+def rg_binary():
+    """Return the ripgrep command (list) or None. $RG overrides PATH lookup."""
+    env_rg = os.environ.get("RG")
+    if env_rg:
+        return [env_rg]
+    found = shutil.which("rg")
+    return [found] if found else None
+
+
+def rg_version():
+    cmd = rg_binary()
+    if not cmd:
+        return "python-fallback (ripgrep not found; regex word search over the same files)"
+    try:
+        return subprocess.run(cmd + ["--version"], capture_output=True, text=True, timeout=20).stdout.splitlines()[0]
+    except Exception as exc:  # pragma: no cover - environment dependent
+        return "rg unavailable: %s" % exc
+
+
+def files_with_word(root, word, include_tests=True, whole_word=True, ignore_case=False):
+    """Code files (repo-relative) that contain `word` as a whole word.
+
+    Uses ripgrep when available, otherwise a regex scan with the same semantics
+    (fixed string, whole word by default, code extensions only, skip dirs ignored).
+    """
+    root = Path(root)
+    cmd = rg_binary()
+    hits = set()
+    if cmd:
+        args = cmd + ["-l", "-F", "--no-messages", "--no-ignore", "--hidden"]
+        if whole_word:
+            args.append("-w")
+        if ignore_case:
+            args.append("-i")
+        for ext in sorted(CODE_EXTS):
+            args += ["-g", "*" + ext]
+        for d in sorted(SKIP_DIRS):
+            args += ["-g", "!%s/" % d]
+        args += ["--", word, "."]
+        res = subprocess.run(args, cwd=str(root), capture_output=True, text=True, timeout=300)
+        for line in res.stdout.splitlines():
+            hits.add(line[2:] if line.startswith("./") else line)
+    else:
+        body = re.escape(word)
+        if whole_word:
+            body = r"(?<![A-Za-z0-9_])" + body + r"(?![A-Za-z0-9_])"
+        pat = re.compile(body, re.I if ignore_case else 0)
+        for rel in iter_code_files(root):
+            try:
+                text = (root / rel).read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            if pat.search(text):
+                hits.add(rel)
+    if not include_tests:
+        hits = {h for h in hits if not is_test_path(h)}
+    return hits
+
+
+def clean_env(home, venv_bin, extra=None):
+    """Minimal environment: no LLM keys, no cloud credentials, no proxies."""
+    env = {
+        "HOME": str(home),
+        "PATH": "%s:/usr/bin:/bin:/usr/sbin:/sbin" % venv_bin,
+        "LANG": "C.UTF-8",
+        "PYTHONHASHSEED": "0",
+        "NO_COLOR": "1",
+    }
+    if extra:
+        env.update(extra)
+    return env
+
+
+def log(msg):
+    sys.stderr.write("[gv] %s\n" % msg)
+    sys.stderr.flush()

package/tools/graphify-validation/lib/licenses.py

@@ -0,0 +1,47 @@
+"""License inventory of the installed distributions (run with the venv python). Stdlib only."""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from importlib import metadata
+
+COPYLEFT = re.compile(r"\b(AGPL|GPL|LGPL|SSPL|EUPL|MPL|CC-BY-SA|OSL)\b", re.I)
+PERMISSIVE = re.compile(r"\b(MIT|BSD|Apache|ISC|PSF|Python Software Foundation|Unlicense|CC0|HPND|Zlib)\b", re.I)
+
+
+def classify(text):
+    if not text:
+        return "UNKNOWN"
+    if COPYLEFT.search(text):
+        return "REVIEW (copyleft-family)"
+    if PERMISSIVE.search(text):
+        return "permissive"
+    return "UNKNOWN"
+
+
+def main():
+    rows = []
+    for dist in sorted(metadata.distributions(), key=lambda d: (d.metadata["Name"] or "").lower()):
+        name = dist.metadata["Name"]
+        if name.lower() in ("pip", "setuptools", "wheel"):
+            continue
+        meta = dist.metadata
+        expr = meta.get("License-Expression") or ""
+        lic = (meta.get("License") or "").strip().splitlines()[0] if meta.get("License") else ""
+        classifiers = [c.split("::")[-1].strip() for c in meta.get_all("Classifier") or [] if c.startswith("License ::")]
+        text = " ".join([expr, lic] + classifiers)
+        files = [str(f) for f in (dist.files or []) if re.search(r"(LICEN[CS]E|NOTICE|COPYING)", str(f), re.I)]
+        rows.append({"name": name, "version": dist.version, "license_expression": expr, "license_field": lic[:80],
+                     "classifiers": classifiers, "license_files": files[:4], "class": classify(text),
+                     "has_license_file": bool(files)})
+    summary = {"total": len(rows),
+               "permissive": sum(1 for r in rows if r["class"] == "permissive"),
+               "review": [r["name"] for r in rows if r["class"].startswith("REVIEW")],
+               "unknown": [r["name"] for r in rows if r["class"] == "UNKNOWN"],
+               "without_license_file": [r["name"] for r in rows if not r["has_license_file"]]}
+    json.dump({"distributions": rows, "summary": summary}, sys.stdout, indent=2)
+
+
+if __name__ == "__main__":
+    main()