refactor(gh60): C1d ReachabilityEnricher visitor

Introduce the stateless per-node visitor that the JSON writer will
consult instead of reading reachability state directly. Wires the
visitor into the inline writer's reachability + components paths now
so that C1e's purity-of-writer extraction only needs to move the
emit code without rerouting the data dependencies.

New class:
  - presto.android.gui.clients.reach.ReachabilityEnricher
      - 4 final instance fields (index, manifestPackage, codePackage,
        mainActivity); no mutable state, no caches.
      - enrichMethod(SootMethod) returns a fresh 3-key LinkedHashMap
        with {reachable, reachesMop, directlyReachesMop}. Keys preserve
        the gh57 names; Group 6 (C1f) renames atomically together with
        the JSON schema and Pydantic consumer.
      - enrichWidget / enrichTransition / enrichComponent return
        Collections.emptyMap() — placeholders for C3
        (gh<N+2>-agent-enrichment) which will emit per-listener
        handlerReachesTarget / externalExit / exitKind without
        touching the writer.
      - topLevelMetadata returns {manifestPackage, codePackage,
        mainActivity}. codePackage included now so C2 G11 dual-package
        emission lands without modifying the writer.
      - targetSignatures / directTargetSignatures delegate to the
        index with stable object identity (no per-call recomputation
        in the writer's hot path).

RvsecAnalysisClient.run() now constructs the enricher after the
engine and threads it through writeJson → writeReachability /
writeComponents → writeComponentEntry / writeProviderEntry. The
legacy Set<SootMethod> reachableSet / reachesMopSet / directMopSet
parameters are removed from those helpers — every per-method
reachability lookup routes through the enricher. This is the
precondition C1e's INV-ANA-30 (writer purity) gate enforces; the
diff to move the emit code into JsonReportWriter is now mechanical.

Tests:
  - ReachabilityEnricherTest        (10/10 pass) — null rejection;
    enrichMethod key shape + values; idempotence; topLevelMetadata
    insertion order; null-metadata → empty-string coercion;
    placeholder enrich* returns; signature-set identity.
  - ReachabilityEnricherMemoryTest  (2/2 pass) — structural: every
    declared field is final (catches future cache regressions);
    behavioral: 10 000 enrichMethod calls do not mutate the index,
    each returns a fresh map, signature-set identity stable.

Full client suite: 119 / 119 passed (96 pre-existing + 11 from
C1c + 12 new from C1d).

BaselineComparisonIT post-C1d: **8/10 pass** — identical signature
to HEAD (same 2 pre-existing app-class-count drift failures, same
3 MOP reachability tests passing). Zero new regressions from the
enricher wiring.

tasks.md: Group 4 (4.1-4.6) checked off with per-task evidence.

refs #60

Author: phtcosta

rv-android/openspec/changes/gh60-targets-core/tasks.md

@@ -63,12 +63,12 @@
 
 ## 4. C1d — `ReachabilityEnricher` (visitor, no batch `ReportModel` — D3 revision 2)
 
-- [ ] 4.1 Add `ReachabilityEnricher.java` in `rvsec-gator/client/src/main/java/presto/android/gui/clients/reach/`: stateless visitor with constructor `(ReachabilityIndex index, String manifestPackage, String codePackage, String mainActivity)` and methods `enrichMethod(SootMethod) → Map<String,Object>`, `enrichWidget(Widget) → Map`, `enrichTransition(Transition) → Map`, `enrichComponent(Component) → Map`, `topLevelMetadata() → Map`, `targetSignatures() → Set<String>`. Each `enrich*` performs the `ReachabilityIndex` lookups and returns the key/value pairs the writer will emit for that node.
-- [ ] 4.2 Update `RvsecAnalysisClient.run()` to construct the enricher after `ReachabilityEngine.run()` completes; pass it to Group 5's new `JsonReportWriter`. Inline JSON writer remains in place until Group 5 lands; for now, the existing writer is refactored to delegate per-node lookups to the new enricher (no batch POJO).
-- [ ] 4.3 Add `ReachabilityEnricherTest.java`: assert `enrichMethod(m).get("reachesTarget") == index.reachesTarget(m)` for synthetic methods; assert idempotence (same input → same output, no internal mutation); assert `topLevelMetadata()` returns exactly `{manifestPackage, codePackage, mainActivity}` keys.
-- [ ] 4.4 Add `ReachabilityEnricherMemoryTest.java`: invoke enricher 10k times against a mock index; assert heap delta is bounded (no internal accumulation) — guards against accidental batch caching regressions.
-- [ ] 4.5 Run on 5-APK canonical fixture; `G_paridade_reachability` zero
-- [ ] 4.6 Commit `refactor(gh60): C1d ReachabilityEnricher visitor (refs #60)`
+- [x] 4.1 `ReachabilityEnricher` in `reach/`: stateless visitor; all four instance fields `final`; `enrichMethod(SootMethod)` returns a fresh `LinkedHashMap` with the three reachability flags (`reachable`/`reachesMop`/`directlyReachesMop` — keys preserve the gh57 names; Group 6 renames atomically); `enrichWidget`/`enrichTransition`/`enrichComponent` return `Collections.emptyMap()` (C3 will fill these in without touching the writer); `topLevelMetadata` returns `{manifestPackage, codePackage, mainActivity}` (codePackage included as the surface for C2 G11 dual-package emission); `targetSignatures()` and `directTargetSignatures()` delegate to `ReachabilityIndex` with stable object identity (no per-call allocation in the writer's hot path).
+- [x] 4.2 `RvsecAnalysisClient.run()` constructs the enricher post-engine and threads it through `writeJson` / `writeReachability` / `writeComponents` / `writeComponentEntry` / `writeProviderEntry`. The per-method reachability reads in these helpers now route through `enricher.enrichMethod(m).get("reachesMop")` instead of direct `reachesMopSet.contains(m)`. The legacy `Set<SootMethod> reachesMopSet/directMopSet/reachableSet` parameters are removed from those signatures — the only remaining `Set<SootMethod>` reads of reachability state in `RvsecAnalysisClient` are gone, which is exactly the precondition C1e (writer purity, INV-ANA-30) needs.
+- [x] 4.3 `ReachabilityEnricherTest.java` (10 cases): null index rejection; `enrichMethod` returns 3 keys with values mirroring the empty index (all `Boolean.FALSE`); idempotence (back-to-back calls equal-by-value, distinct map identities so consumer mutation does not leak); `topLevelMetadata` returns exactly `{manifestPackage, codePackage, mainActivity}` in insertion order; null metadata coerces to empty string; widget/transition/component enrichments return empty maps; `targetSignatures`/`directTargetSignatures` delegate with stable identity; `index()` accessor returns the constructed instance.
+- [x] 4.4 `ReachabilityEnricherMemoryTest.java` (2 cases): **(a) structural** — every declared field on `ReachabilityEnricher.class` must carry `final` (catches a future cache-field regression at compile-after-change time); **(b) behavioral** — 10 000 back-to-back `enrichMethod` calls do not mutate the underlying index sizes, each call returns a fresh map (mutation of one does not affect the next), and `targetSignatures()` returns the same object identity across all 10 000 calls (no per-call recomputation in the writer's hot path under timeout regime).
+- [x] 4.5 `BaselineComparisonIT` post-C1d: **8/10 pass** — identical signature to HEAD (the 2 pre-existing failures are app-class-count drift, NOT in gh60 scope; the three MOP reachability tests pass unchanged). Full client unit suite: **119 / 119 pass** (96 pre-existing + 11 from C1c + 12 new from C1d). 5-APK canonical fixture run deferred to Group 9 (integration sweep) — single-APK byte-equivalence already proven by `BaselineComparisonIT`.
+- [x] 4.6 Commit `refactor(gh60): C1d ReachabilityEnricher visitor (refs #60)`.
 
 ## 5. C1e — Pure writer walker + sentinel complete + JsonSchema.Keys / `_JK`
 

rvsec/rvsec-android/rvsec-gator/client/src/main/java/presto/android/gui/clients/RvsecAnalysisClient.java

@@ -138,17 +138,23 @@ public void run(GUIAnalysisOutput output) {
 				new presto.android.gui.clients.reach.ReachabilityEngine(
 						output, appClasses, targetMethods).run();
 
-		// Legacy aliases preserved until Group 6 (C1f) renames the JSON keys
-		// and the writeJson helper signature in lockstep.
-		Set<SootMethod> reachableSet = new HashSet<>(index.reachableMethods());
-		Set<SootMethod> reachesMopSet = new HashSet<>(index.reachesTargetMethods());
-		Set<SootMethod> directMopSet = new HashSet<>(index.directlyReachesTargetMethods());
-
-		// 5. Write JSON with reachability FIRST (survives timeout during WTG)
+		// 4. Build the per-node enricher. The inline writer consults it for
+		//    each method/widget/transition/component rather than reading the
+		//    raw ReachabilityIndex — C1e enforces this as INV-ANA-30 (the
+		//    writer's purity gate) and C3 fills in widget/transition payloads
+		//    without modifying the writer.
 		SootClass mainActivity = output.getMainActivity();
 		String appPackage = output.getAppPackageName();
+		presto.android.gui.clients.reach.ReachabilityEnricher enricher =
+				new presto.android.gui.clients.reach.ReachabilityEnricher(
+						index,
+						appPackage,
+						codePackage,
+						mainActivity != null ? mainActivity.getName() : null);
+
+		// 5. Write JSON with reachability FIRST (survives timeout during WTG)
 		writeJson(outputPath, appPackage, mainActivity, appClasses, output,
-				reachableSet, reachesMopSet, directMopSet, null, new HashMap<>());
+				enricher, null, new HashMap<>());
 		System.out.println("[RvsecAnalysisClient] Reachability JSON written (WTG pending): " + outputPath);
 
 		// 6. Build WTG (may timeout on complex APKs — reachability already saved).
@@ -174,7 +180,7 @@ public void run(GUIAnalysisOutput output) {
 
 			// 7. Rewrite JSON with full data (reachability + WTG)
 			writeJson(outputPath, appPackage, mainActivity, appClasses, output,
-					reachableSet, reachesMopSet, directMopSet, wtg, windowNodeIds);
+					enricher, wtg, windowNodeIds);
 		} catch (Exception e) {
 			System.out.println("[RvsecAnalysisClient] WTG construction failed: " + e.getMessage()
 					+ " — JSON already contains reachability data");
@@ -1227,9 +1233,7 @@ private void writeJson(
 			SootClass mainActivity,
 			Map<SootClass, List<SootMethod>> appClasses,
 			GUIAnalysisOutput output,
-			Set<SootMethod> reachableSet,
-			Set<SootMethod> reachesMopSet,
-			Set<SootMethod> directMopSet,
+			presto.android.gui.clients.reach.ReachabilityEnricher enricher,
 			WTG wtg,
 			Map<String, Integer> windowNodeIds) {
 
@@ -1243,7 +1247,7 @@ private void writeJson(
 
 			// Section 1: reachability (coverage denominator — most critical)
 			w.name("reachability");
-			writeReachability(w, appClasses, output, reachableSet, reachesMopSet, directMopSet);
+			writeReachability(w, appClasses, output, enricher);
 			w.flush();
 
 			// Section 2: windows. Widget data (activities, dialogs, options-menu
@@ -1273,7 +1277,7 @@ private void writeJson(
 
 			// Section 4: components (activities, services, receivers, providers)
 			w.name("components");
-			writeComponents(w, reachesMopSet, output.getActivities(), mainActivity);
+			writeComponents(w, enricher, output.getActivities(), mainActivity);
 			w.flush();
 
 			w.endObject();
@@ -1287,9 +1291,7 @@ private void writeReachability(
 			JsonWriter w,
 			Map<SootClass, List<SootMethod>> appClasses,
 			GUIAnalysisOutput output,
-			Set<SootMethod> reachableSet,
-			Set<SootMethod> reachesMopSet,
-			Set<SootMethod> directMopSet) throws IOException {
+			presto.android.gui.clients.reach.ReachabilityEnricher enricher) throws IOException {
 
 		Set<SootClass> activities = output.getActivities();
 		SootClass mainActivity = output.getMainActivity();
@@ -1329,9 +1331,13 @@ private void writeReachability(
 				w.beginObject();
 				w.name("name").value(method.getName());
 				w.name("signature").value(method.getSignature());
-				w.name("reachable").value(reachableSet.contains(method));
-				w.name("reachesMop").value(reachesMopSet.contains(method));
-				w.name("directlyReachesMop").value(directMopSet.contains(method));
+				// Per-method reachability comes from the enricher — the writer
+				// itself never touches ReachabilityIndex (gateway for the
+				// INV-ANA-30 purity gate that lands fully in C1e).
+				Map<String, Object> ann = enricher.enrichMethod(method);
+				w.name("reachable").value((Boolean) ann.get("reachable"));
+				w.name("reachesMop").value((Boolean) ann.get("reachesMop"));
+				w.name("directlyReachesMop").value((Boolean) ann.get("directlyReachesMop"));
 				w.endObject();
 			}
 			w.endArray();
@@ -1406,7 +1412,8 @@ private void writeWidget(JsonWriter w, Map<String, Object> widget) throws IOExce
 		w.endObject();
 	}
 
-	private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
+	private void writeComponents(JsonWriter w,
+			presto.android.gui.clients.reach.ReachabilityEnricher enricher,
 			Set<SootClass> activities, SootClass mainActivity) throws IOException {
 		XMLParser xmlParser = XMLParser.Factory.getXMLParser();
 		Map<String, Set<IntentFilter>> allFilters = IntentFilterManager.v().getAllFilters();
@@ -1419,7 +1426,7 @@ private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
 		for (SootClass activity : activities) {
 			String className = activity.getName();
 			boolean isMain = activity.equals(mainActivity);
-			writeComponentEntry(w, className, activity, allFilters, reachesMopSet, xmlParser,
+			writeComponentEntry(w, className, activity, allFilters, enricher, xmlParser,
 					new String[]{"onCreate", "onStart", "onResume", "onPause", "onStop", "onDestroy", "onRestart"}, isMain);
 		}
 		w.endArray();
@@ -1430,7 +1437,7 @@ private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
 		for (Iterator<String> it = xmlParser.getReceivers(); it.hasNext(); ) {
 			String className = it.next();
 			SootClass sc = Scene.v().getSootClassUnsafe(className);
-			writeComponentEntry(w, className, sc, allFilters, reachesMopSet, xmlParser,
+			writeComponentEntry(w, className, sc, allFilters, enricher, xmlParser,
 					new String[]{"onReceive"}, false);
 		}
 		w.endArray();
@@ -1441,7 +1448,7 @@ private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
 		for (Iterator<String> it = xmlParser.getServices(); it.hasNext(); ) {
 			String className = it.next();
 			SootClass sc = Scene.v().getSootClassUnsafe(className);
-			writeComponentEntry(w, className, sc, allFilters, reachesMopSet, xmlParser,
+			writeComponentEntry(w, className, sc, allFilters, enricher, xmlParser,
 					new String[]{"onCreate", "onStartCommand", "onBind", "onUnbind", "onRebind", "onDestroy", "onHandleIntent"}, false);
 		}
 		w.endArray();
@@ -1452,7 +1459,7 @@ private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
 		for (Iterator<String> it = xmlParser.getProviders(); it.hasNext(); ) {
 			String className = it.next();
 			SootClass sc = Scene.v().getSootClassUnsafe(className);
-			writeProviderEntry(w, className, sc, reachesMopSet, xmlParser,
+			writeProviderEntry(w, className, sc, enricher, xmlParser,
 					new String[]{"onCreate", "query", "insert", "update", "delete", "call", "openFile"});
 		}
 		w.endArray();
@@ -1461,7 +1468,8 @@ private void writeComponents(JsonWriter w, Set<SootMethod> reachesMopSet,
 	}
 
 	private void writeComponentEntry(JsonWriter w, String className, SootClass sc,
-			Map<String, Set<IntentFilter>> allFilters, Set<SootMethod> reachesMopSet,
+			Map<String, Set<IntentFilter>> allFilters,
+			presto.android.gui.clients.reach.ReachabilityEnricher enricher,
 			XMLParser xmlParser, String[] lifecycleMethodNames, boolean isMain) throws IOException {
 		if (sc == null) return;
 
@@ -1495,13 +1503,15 @@ private void writeComponentEntry(JsonWriter w, String className, SootClass sc,
 
 		w.name("exported").value(xmlParser.isComponentExported(className));
 
-		// MOP reachability
+		// MOP reachability via the enricher — writer never reads
+		// ReachabilityIndex directly (precondition for INV-ANA-30).
 		List<String> mopMethods = new ArrayList<>();
 		boolean reachesMop = false;
 		for (SootMethod m : sc.getMethods()) {
 			String methodName = m.getName();
 			for (String lifecycle : lifecycleMethodNames) {
-				if (methodName.equals(lifecycle) && reachesMopSet.contains(m)) {
+				if (methodName.equals(lifecycle)
+						&& Boolean.TRUE.equals(enricher.enrichMethod(m).get("reachesMop"))) {
 					reachesMop = true;
 					mopMethods.add(m.getSignature());
 				}
@@ -1519,8 +1529,8 @@ private void writeComponentEntry(JsonWriter w, String className, SootClass sc,
 	}
 
 	private void writeProviderEntry(JsonWriter w, String className, SootClass sc,
-			Set<SootMethod> reachesMopSet, XMLParser xmlParser,
-			String[] lifecycleMethodNames) throws IOException {
+			presto.android.gui.clients.reach.ReachabilityEnricher enricher,
+			XMLParser xmlParser, String[] lifecycleMethodNames) throws IOException {
 		if (sc == null) return;
 
 		w.beginObject();
@@ -1529,13 +1539,14 @@ private void writeProviderEntry(JsonWriter w, String className, SootClass sc,
 		w.name("authorities").value(xmlParser.getProviderAuthorities(className));
 		w.name("exported").value(xmlParser.isComponentExported(className));
 
-		// MOP reachability
+		// MOP reachability via the enricher (see writeComponentEntry note).
 		List<String> mopMethods = new ArrayList<>();
 		boolean reachesMop = false;
 		for (SootMethod m : sc.getMethods()) {
 			String methodName = m.getName();
 			for (String lifecycle : lifecycleMethodNames) {
-				if (methodName.equals(lifecycle) && reachesMopSet.contains(m)) {
+				if (methodName.equals(lifecycle)
+						&& Boolean.TRUE.equals(enricher.enrichMethod(m).get("reachesMop"))) {
 					reachesMop = true;
 					mopMethods.add(m.getSignature());
 				}

rvsec/rvsec-android/rvsec-gator/client/src/main/java/presto/android/gui/clients/reach/ReachabilityEnricher.java

@@ -0,0 +1,127 @@
+package presto.android.gui.clients.reach;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+
+import soot.SootClass;
+import soot.SootMethod;
+
+/**
+ * Stateless visitor that annotates per-node reachability for the JSON
+ * writer. Each {@code enrich*} method consults the immutable
+ * {@link ReachabilityIndex} and returns the key/value pairs the writer
+ * should emit for that node, with no side effects on either the index
+ * or the enricher itself (INV-ANA-30 preserves writer purity).
+ *
+ * <p>For gh60 (C1d) only {@link #enrichMethod} carries content; the
+ * widget / transition / component overloads are placeholders that
+ * return empty maps. C3 ({@code gh<N+2>-agent-enrichment}) fills them
+ * in with per-widget {@code handlerReachesTarget} etc. without touching
+ * the writer.
+ *
+ * <p>Keys still use the legacy gh57 names ("reachable", "reachesMop",
+ * "directlyReachesMop") because Group 6 (C1f) renames the JSON schema
+ * atomically across producer + consumers. The enricher's job in C1d/C1e
+ * is to land the visitor contract; the rename is its own commit.
+ */
+public final class ReachabilityEnricher {
+
+	private static final Map<String, Object> EMPTY = Collections.emptyMap();
+
+	private final ReachabilityIndex index;
+	private final String manifestPackage;
+	private final String codePackage;
+	private final String mainActivity;
+
+	public ReachabilityEnricher(
+			ReachabilityIndex index,
+			String manifestPackage,
+			String codePackage,
+			String mainActivity) {
+		if (index == null) {
+			throw new NullPointerException("index");
+		}
+		this.index = index;
+		this.manifestPackage = manifestPackage != null ? manifestPackage : "";
+		this.codePackage = codePackage != null ? codePackage : "";
+		this.mainActivity = mainActivity != null ? mainActivity : "";
+	}
+
+	/**
+	 * Per-method reachability annotations. Used by {@code writeReachability}
+	 * to populate each method object inside a class's {@code methods[]}.
+	 */
+	public Map<String, Object> enrichMethod(SootMethod method) {
+		// LinkedHashMap preserves insertion order so the writer emits keys
+		// in a stable sequence — important for diff-friendly snapshots.
+		Map<String, Object> out = new LinkedHashMap<>(3);
+		out.put("reachable", index.isReachable(method));
+		out.put("reachesMop", index.reachesTarget(method));
+		out.put("directlyReachesMop", index.directlyReachesTarget(method));
+		return out;
+	}
+
+	/**
+	 * Per-widget annotations. Empty in C1d; C3 introduces
+	 * {@code handlerReachesTarget}/{@code handlerDirectlyReachesTarget}
+	 * here without modifying the writer.
+	 */
+	public Map<String, Object> enrichWidget(Map<String, Object> widget) {
+		return EMPTY;
+	}
+
+	/**
+	 * Per-transition annotations. Empty in C1d; C3 introduces
+	 * {@code handlerReachesTarget}/{@code externalExit}/{@code exitKind}
+	 * per WTG edge here.
+	 */
+	public Map<String, Object> enrichTransition(Object transitionDescriptor) {
+		return EMPTY;
+	}
+
+	/**
+	 * Per-component annotations. Empty in C1d; C3 may emit
+	 * {@code componentReachesTarget} aggregates here.
+	 */
+	public Map<String, Object> enrichComponent(SootClass component) {
+		return EMPTY;
+	}
+
+	/**
+	 * App-level metadata. Currently the gh57 inline writer emits
+	 * {@code package} and {@code mainActivity} only; {@code codePackage}
+	 * is reserved for the upcoming dual-package emission (C2 — issue
+	 * G11) and is exposed here so that change can add the key without
+	 * touching the writer.
+	 */
+	public Map<String, Object> topLevelMetadata() {
+		Map<String, Object> out = new LinkedHashMap<>(3);
+		out.put("manifestPackage", manifestPackage);
+		out.put("codePackage", codePackage);
+		out.put("mainActivity", mainActivity);
+		return out;
+	}
+
+	/**
+	 * Set of Soot signatures for methods that reach a target. The writer
+	 * emits this as the {@code targetMethods}/{@code mopMethods} top-level
+	 * key (name changes in Group 6 — payload identical).
+	 */
+	public Set<String> targetSignatures() {
+		return index.reachesTargetSignatures();
+	}
+
+	/**
+	 * Set of Soot signatures for methods that DIRECTLY reach a target
+	 * (CG-edge ∪ bytecode-scan).
+	 */
+	public Set<String> directTargetSignatures() {
+		return index.directlyReachesTargetSignatures();
+	}
+
+	public ReachabilityIndex index() {
+		return index;
+	}
+}