android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/dump/dump.js

@@ -0,0 +1,1028 @@
+import {
+  buildNameTraceLookup,
+  LITERAL_NAME_STRATEGIES,
+  nameTraceKey,
+} from "../contracts/name-traceability.js";
+const INDENT = "  ";
+const HEX_HASH = /^[0-9a-f]{10,}$/i;
+function pad(depth) {
+  return INDENT.repeat(depth);
+}
+/** `tag:caseId/subkind/hash` -> `tag:hash6` (subkind duplicates {kind}, the
+ * hash alone is the only part that is actually unique per entity); ids with
+ * no "/" or a non-hash local part pass through unchanged. */
+function shortId(id) {
+  const colon = id.indexOf(":");
+  if (colon === -1) return id;
+  const tag = id.slice(0, colon);
+  const segments = id.slice(colon + 1).split("/");
+  const local = segments[segments.length - 1] ?? "";
+  return `${tag}:${HEX_HASH.test(local) ? local.slice(0, 6) : local}`;
+}
+function fmtSupported(value) {
+  if (value === undefined) return "?";
+  if (value.status === "unresolved")
+    return `?<${shortId(value.unresolvedRef)}>`;
+  return typeof value.value === "string"
+    ? `"${value.value}"`
+    : JSON.stringify(value.value);
+}
+/** For lists of literal values (e.g. feature option labels) — no id shortening. */
+function fmtList(label, items, depth) {
+  if (items.length === 0) return "";
+  return `\n${pad(depth)}${label}: [${items.join(", ")}]`;
+}
+/** For lists of cross-reference ids. */
+function fmtRefList(label, refs, depth) {
+  if (refs.length === 0) return "";
+  return `\n${pad(depth)}${label}: [${refs.map(shortId).join(", ")}]`;
+}
+function fmtTextItems(label, items, depth) {
+  if (items.length === 0) return "";
+  const lines = items.map(
+    (item) => `\n${pad(depth + 1)}- ${item.text} <${shortId(item.id)}>`,
+  );
+  return `\n${pad(depth)}${label}:` + lines.join("");
+}
+function fmtAlternatives(alternatives, depth) {
+  if (!alternatives || alternatives.length === 0) return "";
+  const lines = alternatives.map(
+    (alt, index) =>
+      `\n${pad(depth + 1)}OR[${index}]: [${alt.conditionRefs.map(shortId).join(", ")}]`,
+  );
+  return `\n${pad(depth)}alternatives:` + lines.join("");
+}
+function dumpUnresolved(items) {
+  if (items.length === 0) return "Unresolved: none";
+  const lines = [`Unresolved (${items.length}):`];
+  for (const item of items) {
+    lines.push(
+      `${pad(1)}<${shortId(item.id)}> <${shortId(item.ownerRef)}> ${item.fieldPath} ` +
+        `${item.reasonCode}: ${item.message}`,
+    );
+  }
+  return lines.join("\n");
+}
+function indexBy(items) {
+  return new Map(items.map((item) => [item.id, item]));
+}
+function edgeKey(sourceAreaRef, controlRef, actionRef) {
+  return `${sourceAreaRef}::${controlRef}::${actionRef}`;
+}
+function buildSourceFactsIndex(sourceFacts) {
+  if (!sourceFacts) return undefined;
+  return {
+    factsById: indexBy(sourceFacts.facts),
+    evidenceById: indexBy(sourceFacts.evidence),
+  };
+}
+/** The first `component` SourceFact reachable from an Area/Control/Action's
+ * own `sourceFactRefs` — the JVM/Compose declaration the entity was lifted
+ * from, when the run's source-facts.json was supplied to the dump. */
+function componentFact(sourceFactRefs, idx) {
+  for (const ref of sourceFactRefs) {
+    const fact = idx.factsById.get(ref);
+    if (fact && fact.kind === "component") return fact;
+  }
+  return undefined;
+}
+function basename(path) {
+  const index = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return index === -1 ? path : path.slice(index + 1);
+}
+/** Basenames shared by more than one distinct full path within a given
+ * `@Anchor` universe (one dump() call): those must keep their full path to
+ * stay unambiguous, every other anchor in that same universe can shorten to
+ * its basename alone. Deeply nested paths that only ever differ by directory
+ * (e.g. every merged-manifest candidate) collapse to one readable line. */
+function collidingBasenames(paths) {
+  const byBasename = new Map();
+  for (const path of paths) {
+    const name = basename(path);
+    const fullPaths = byBasename.get(name) ?? new Set();
+    fullPaths.add(path);
+    byBasename.set(name, fullPaths);
+  }
+  const collisions = new Set();
+  for (const [name, fullPaths] of byBasename) {
+    if (fullPaths.size > 1) collisions.add(name);
+  }
+  return collisions;
+}
+/** `path:startLine-endLine`, degrading to `path:startLine` for a single-line
+ * range. `path` is the file's basename unless it collides with another
+ * distinct full path in `collisions` (see `collidingBasenames`), in which
+ * case the full path (relative to the project root, matching evidence.path/
+ * SourceLocation.path) is kept so the anchor stays unambiguous. Omitting
+ * `collisions` (no known universe to check against) keeps the full path.
+ * This is the `@Anchor` token's payload (DEVELOPER.md). */
+function fmtAnchorLocation(location, collisions) {
+  const { path, range } = location;
+  const name = basename(path);
+  const displayPath =
+    collisions !== undefined && !collisions.has(name) ? name : path;
+  return range.startLine === range.endLine
+    ? `${displayPath}:${range.startLine}`
+    : `${displayPath}:${range.startLine}-${range.endLine}`;
+}
+/** Inline `@Anchor` token, per DEVELOPER.md's common shape: same line as the
+ * entity header, right after its `"text"` (or `{kind}` when there is no
+ * "text"), before any trailing `->`. */
+function fmtAnchor(location, collisions) {
+  if (!location) return "";
+  return ` @${fmtAnchorLocation(location, collisions)}`;
+}
+/** Prefers the evidence backing the class declaration itself over incidental
+ * support entries (manifest merger, layout binding, ...). */
+function preferredEvidence(fact, idx) {
+  const preferred =
+    fact.support.find((link) => link.role.includes("class declaration")) ??
+    fact.support[0];
+  return preferred ? idx.evidenceById.get(preferred.evidenceRef) : undefined;
+}
+/** `Symbol` token (DEVELOPER.md): "prefer className = functionName > other
+ * source code symbols. Short Name, not Qualified Name" — strips package
+ * qualification and parameter lists down to the bare identifier:
+ * "com.foo.Bar#baz(int)" -> "baz" (function wins over its class), "com.foo.Bar"
+ * -> "Bar", "@id/ivClose" -> "ivClose". */
+function shortSymbol(raw) {
+  const withoutIdPrefix = raw.replace(/^@id\//u, "");
+  const hashIndex = withoutIdPrefix.indexOf("#");
+  if (hashIndex === -1) {
+    const segments = withoutIdPrefix.split(".");
+    return segments[segments.length - 1] || withoutIdPrefix;
+  }
+  return withoutIdPrefix.slice(hashIndex + 1).replace(/\([^]*\)\s*$/u, "");
+}
+/** Area/Control identity from a matching name-traceability.json entry —
+ * the precomputed, ranked identity decision Stage 2 itself grounds on (see
+ * agent-render/name-trace.ts), preferred over the source-facts-only
+ * heuristic below because that heuristic has no visibility into competing
+ * candidates (an Area backed by both an Activity and a hosted composable can
+ * pick the composable's generic name over the Activity's real one — see
+ * DEVELOPER.md's WebActivity/Content case). Only a code-origin selected
+ * strategy counts: a literal UI-text strategy (LITERAL_NAME_STRATEGIES) means
+ * this entity's *name* came from real text, not a code symbol — nothing to
+ * borrow here, so the source-facts heuristic still owns Symbol/@Anchor. */
+function identityFromNameTrace(entry) {
+  if (!entry) return undefined;
+  const selected = entry.attempts.find(
+    (attempt) => attempt.outcome === "selected",
+  );
+  if (!selected?.rawValue || LITERAL_NAME_STRATEGIES.has(selected.strategy))
+    return undefined;
+  const selectedLocations = entry.sourceLocations.filter(
+    (location) => location.usage === "selected",
+  );
+  const preferred =
+    selectedLocations.find((location) => location.symbol !== undefined) ??
+    selectedLocations[0];
+  return { symbol: selected.rawValue, evidence: preferred };
+}
+/** Tier 1 — className#functionName (or bare #functionName when the owning
+ * class can't be resolved): the `symbol` an analyzer attached to the
+ * evidence itself backing one of this entity's own SourceFacts. Covers
+ * ~100% of JVM/Compose-backed Controls/Actions/Effects (verified against
+ * suvinemusicx/latest); XML-declared entities have no evidence.symbol. */
+function symbolFromOwnEvidence(sourceFactRefs, idx) {
+  for (const ref of sourceFactRefs) {
+    const fact = idx.factsById.get(ref);
+    if (!fact) continue;
+    for (const support of fact.support) {
+      const evidence = idx.evidenceById.get(support.evidenceRef);
+      if (evidence?.symbol) return { symbol: evidence.symbol, evidence };
+    }
+  }
+  return undefined;
+}
+/** Tier 1 continued — Actions/Effects reference an `interaction-binding` or
+ * `behavior-effect` fact rather than the `callback` fact directly; follow
+ * `callbackKey` one hop to reach the owning method's symbol/evidence. */
+function symbolViaCallback(sourceFactRefs, idx) {
+  for (const ref of sourceFactRefs) {
+    const callbackKey = idx.factsById.get(ref)?.data?.callbackKey;
+    if (!callbackKey) continue;
+    const callback = idx.factsById.get(callbackKey);
+    if (!callback) continue;
+    const direct = symbolFromOwnEvidence([callback.id], idx);
+    if (direct) return direct;
+    const callableSymbol = callback.data.callableSymbol;
+    if (callableSymbol)
+      return {
+        symbol: callableSymbol,
+        evidence: preferredEvidence(callback, idx),
+      };
+  }
+  return undefined;
+}
+/** Tier 2 — other source code symbols: declaration-time identifiers that
+ * aren't a class/method symbol (XML view id, icon/content-description
+ * anchors) for entities an analyzer can't attach JVM symbol evidence to. */
+function otherCodeSymbol(sourceFactRefs, idx) {
+  for (const ref of sourceFactRefs) {
+    const fact = idx.factsById.get(ref);
+    if (!fact) continue;
+    const evidence = preferredEvidence(fact, idx);
+    if (fact.kind === "ui-element") {
+      const data = fact.data;
+      const symbol = data.symbol ?? data.resourceId;
+      if (symbol) return { symbol, evidence };
+    }
+    if (fact.kind === "callback") {
+      const callableSymbol = fact.data.callableSymbol;
+      if (callableSymbol) return { symbol: callableSymbol, evidence };
+    }
+  }
+  return undefined;
+}
+/** Tier 3 — source code anchor only: the first evidence location reachable
+ * from this entity's own sourceFactRefs, no symbol identity attached. */
+function anchorOnly(sourceFactRefs, idx) {
+  for (const ref of sourceFactRefs) {
+    const fact = idx.factsById.get(ref);
+    if (!fact) continue;
+    const evidence = preferredEvidence(fact, idx);
+    if (evidence) return { evidence };
+  }
+  return undefined;
+}
+/**
+ * Control/Action/Effect source identity, most to least preferred (per
+ * DEVELOPER.md): className#functionName evidence symbol > the same one hop
+ * through a callback reference > other declaration-time symbols (XML view
+ * id, ...) > a bare source anchor (path:line[-line]), no symbol at all.
+ */
+function resolveSourceIdentity(sourceFactRefs, idx) {
+  return (
+    symbolFromOwnEvidence(sourceFactRefs, idx) ??
+    symbolViaCallback(sourceFactRefs, idx) ??
+    otherCodeSymbol(sourceFactRefs, idx) ??
+    anchorOnly(sourceFactRefs, idx) ??
+    {}
+  );
+}
+/**
+ * Area identity: name-traceability's ranked decision first (see
+ * `identityFromNameTrace`), falling back to its own `component` SourceFact's
+ * qualifiedName directly, falling back further to the generic tiered
+ * resolver used by Control/Action/Effect. Takes the raw ref/sourceFactRefs
+ * pair rather than an `Area` object so ReqModel's ReqArea — which carries
+ * the same `areaRef` and a superset `supportRefs` merging the Area's own
+ * sourceFactRefs with its Controls' (see analysis/req-model/build.ts) — can
+ * resolve the identical identity without needing the AreaGraph at all. */
+function areaSourceIdentity(sourceFactRefs, areaRef, sourceFacts, nameTrace) {
+  const fromNameTrace = identityFromNameTrace(
+    nameTrace?.get(nameTraceKey("area", areaRef)),
+  );
+  if (fromNameTrace) return fromNameTrace;
+  if (!sourceFacts) return {};
+  const component = componentFact(sourceFactRefs, sourceFacts);
+  return component
+    ? {
+        symbol: component.data.qualifiedName,
+        evidence: preferredEvidence(component, sourceFacts),
+      }
+    : resolveSourceIdentity(sourceFactRefs, sourceFacts);
+}
+/** Control identity: name-traceability's ranked decision first, falling back
+ * to the generic tiered resolver used by Action/Effect. Same ref/
+ * sourceFactRefs-pair shape as `areaSourceIdentity`, for the same reason:
+ * ReqModel's ReqFeature carries `controlRef` + a superset `supportRefs`. */
+function controlSourceIdentity(
+  sourceFactRefs,
+  controlRef,
+  sourceFacts,
+  nameTrace,
+) {
+  const fromNameTrace = identityFromNameTrace(
+    nameTrace?.get(nameTraceKey("control", controlRef)),
+  );
+  if (fromNameTrace) return fromNameTrace;
+  return sourceFacts ? resolveSourceIdentity(sourceFactRefs, sourceFacts) : {};
+}
+/** `Symbol ` prefix for an entity's header line (empty when unresolved). */
+function fmtSymbolPrefix(identity) {
+  return identity.symbol ? `${shortSymbol(identity.symbol)} ` : "";
+}
+function buildAreaGraphIndex(graph, sourceFacts, nameTraceability) {
+  const edgesByKey = new Map();
+  for (const edge of graph.edges) {
+    const key = edgeKey(edge.sourceAreaRef, edge.controlRef, edge.actionRef);
+    const bucket = edgesByKey.get(key);
+    if (bucket) {
+      bucket.push(edge);
+    } else {
+      edgesByKey.set(key, [edge]);
+    }
+  }
+  return {
+    areasById: indexBy(graph.areas),
+    controlsById: indexBy(graph.controls),
+    actionsById: indexBy(graph.actions),
+    effectsById: indexBy(graph.effects),
+    externalsById: indexBy(graph.externalEndpoints),
+    edgesByKey,
+    sourceFacts: buildSourceFactsIndex(sourceFacts),
+    nameTrace: nameTraceability
+      ? buildNameTraceLookup(nameTraceability.entries)
+      : undefined,
+  };
+}
+/** `-> <area:id> "name" {kind}`, kind omitted when the target isn't in this graph. */
+function fmtAreaRef(ref, area) {
+  const kind = area ? ` {${area.kind}}` : "";
+  return `<${shortId(ref)}> ${area ? fmtSupported(area.name) : "?"}${kind}`;
+}
+function dumpEdgeTarget(edge, idx, depth) {
+  const target = edge.target;
+  let out;
+  if ("unresolvedRef" in target) {
+    out = `\n${pad(depth)}-> ?<${shortId(target.unresolvedRef)}>`;
+  } else if (target.kind === "area") {
+    out = `\n${pad(depth)}-> ${fmtAreaRef(target.ref, idx.areasById.get(target.ref))}`;
+  } else {
+    const external = idx.externalsById.get(target.ref);
+    const kind = external ? ` {${external.kind}}` : "";
+    out = `\n${pad(depth)}-> <${shortId(target.ref)}> ${external ? fmtSupported(external.name) : "?"}${kind}`;
+  }
+  out += fmtRefList("when", edge.conditions, depth + 1);
+  out += fmtAlternatives(edge.conditionAlternatives, depth + 1);
+  return out;
+}
+function dumpEffect(effect, idx, depth, collisions) {
+  const identity = idx.sourceFacts
+    ? resolveSourceIdentity(effect.sourceFactRefs, idx.sourceFacts)
+    : {};
+  const tags = [
+    effect.kind,
+    effect.closePolicy ? `close=${effect.closePolicy}` : undefined,
+    effect.transitionMode ? `transition=${effect.transitionMode}` : undefined,
+    effect.stateKey ? `state=${fmtSupported(effect.stateKey)}` : undefined,
+    effect.value !== undefined
+      ? `value=${fmtSupported(effect.value)}`
+      : undefined,
+  ].filter((tag) => tag !== undefined);
+  let out =
+    `\n${pad(depth)}<${shortId(effect.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${tags.join(", ")}} ${fmtSupported(effect.description)}${fmtAnchor(identity.evidence, collisions)}`;
+  out += fmtAlternatives(effect.conditionAlternatives, depth + 1);
+  out += fmtRefList("unresolved", effect.unresolvedRefs ?? [], depth + 1);
+  return out;
+}
+function dumpAction(action, sourceAreaRef, idx, depth, collisions) {
+  const identity = idx.sourceFacts
+    ? resolveSourceIdentity(action.sourceFactRefs, idx.sourceFacts)
+    : {};
+  let out =
+    `\n${pad(depth)}<${shortId(action.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${action.trigger}}${fmtAnchor(identity.evidence, collisions)}`;
+  out += fmtRefList("pre", action.preconditionRefs, depth + 1);
+  out += fmtAlternatives(action.preconditionAlternatives, depth + 1);
+  for (const ref of action.effectRefs) {
+    const effect = idx.effectsById.get(ref);
+    if (effect) out += dumpEffect(effect, idx, depth + 1, collisions);
+  }
+  const edges =
+    idx.edgesByKey.get(edgeKey(sourceAreaRef, action.controlRef, action.id)) ??
+    [];
+  for (const edge of edges) {
+    out += dumpEdgeTarget(edge, idx, depth + 1);
+  }
+  return out;
+}
+function dumpControl(control, idx, depth, collisions) {
+  const identity = controlSourceIdentity(
+    control.sourceFactRefs,
+    control.id,
+    idx.sourceFacts,
+    idx.nameTrace,
+  );
+  let out =
+    `\n${pad(depth)}<${shortId(control.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${control.kind}} ${fmtSupported(control.name)}${fmtAnchor(identity.evidence, collisions)}`;
+  if (control.enabled) out += ` enabled=${fmtSupported(control.enabled)}`;
+  out += fmtRefList("visible-when", control.visibilityConditions, depth + 1);
+  out += fmtRefList("enabled-when", control.enabledConditions, depth + 1);
+  for (const ref of control.actionRefs) {
+    const action = idx.actionsById.get(ref);
+    if (action)
+      out += dumpAction(action, control.areaRef, idx, depth + 1, collisions);
+  }
+  return out;
+}
+function dumpArea(area, idx, depth, collisions) {
+  const identity = areaSourceIdentity(
+    area.sourceFactRefs,
+    area.id,
+    idx.sourceFacts,
+    idx.nameTrace,
+  );
+  let out =
+    `${pad(depth)}<${shortId(area.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${area.kind}} ${fmtSupported(area.name)}${fmtAnchor(identity.evidence, collisions)}`;
+  out += fmtRefList("conditions", area.conditions, depth + 1);
+  for (const ref of area.controlRefs) {
+    const control = idx.controlsById.get(ref);
+    if (control) out += dumpControl(control, idx, depth + 1, collisions);
+  }
+  return out;
+}
+/** Every evidence path this dump will actually render as an `@Anchor` across
+ * all Areas/Controls/Actions/Effects — the same "one dump() call" collision
+ * universe `dumpGapAudit` computes for its own candidates, reused here so
+ * `collidingBasenames` decides full-path-vs-basename consistently. */
+function allSourceEvidencePaths(graph, idx) {
+  const paths = [];
+  const collect = (identity) => {
+    if (identity.evidence) paths.push(identity.evidence.path);
+  };
+  for (const area of graph.areas) {
+    collect(
+      areaSourceIdentity(
+        area.sourceFactRefs,
+        area.id,
+        idx.sourceFacts,
+        idx.nameTrace,
+      ),
+    );
+  }
+  for (const control of graph.controls) {
+    collect(
+      controlSourceIdentity(
+        control.sourceFactRefs,
+        control.id,
+        idx.sourceFacts,
+        idx.nameTrace,
+      ),
+    );
+  }
+  if (idx.sourceFacts) {
+    for (const action of graph.actions)
+      collect(resolveSourceIdentity(action.sourceFactRefs, idx.sourceFacts));
+    for (const effect of graph.effects)
+      collect(resolveSourceIdentity(effect.sourceFactRefs, idx.sourceFacts));
+  }
+  return paths;
+}
+function dumpEntryPoint(entry, idx) {
+  const roots = entry.rootAreaRefs
+    .map((ref) => fmtAreaRef(ref, idx.areasById.get(ref)))
+    .join(", ");
+  return `${pad(1)}<${shortId(entry.id)}> {${entry.kind}, ${entry.category}} -> ${roots}`;
+}
+/**
+ * Dumps an AreaGraphArtifact as an indented tree instead of JSON. Passing the
+ * matching source-facts.json (same run) additionally resolves each
+ * Area/Control/Action/Effect's `Symbol` (short className/functionName) and
+ * `@Anchor` (declaration location) per DEVELOPER.md. Passing the matching
+ * name-traceability.json (same run) further overrides Area/Control's Symbol/
+ * @Anchor with its precomputed, ranked identity decision when one exists —
+ * see `identityFromNameTrace`; Action/Effect have no name-traceability
+ * coverage and always use the source-facts heuristic. Omitting both, dump
+ * renders exactly as before, with no Symbol/Anchor.
+ */
+export function dumpAreaGraph(graph, sourceFacts, nameTraceability) {
+  const idx = buildAreaGraphIndex(graph, sourceFacts, nameTraceability);
+  const collisions = collidingBasenames(allSourceEvidencePaths(graph, idx));
+  const lines = [];
+  lines.push(
+    `AreaGraph <${graph.caseId}> [${graph.analysisContext.applicationModule}:${graph.analysisContext.buildVariant}]`,
+  );
+  lines.push("Entry Points:");
+  for (const entry of graph.entryPoints) lines.push(dumpEntryPoint(entry, idx));
+  lines.push("Areas:");
+  for (const area of graph.areas)
+    lines.push(dumpArea(area, idx, 1, collisions));
+  if (graph.excludedAreaCandidates && graph.excludedAreaCandidates.length > 0) {
+    lines.push("Excluded Area Candidates:");
+    for (const candidate of graph.excludedAreaCandidates) {
+      lines.push(
+        `${pad(1)}<${shortId(candidate.componentRef)}> excluded: ${candidate.reasonCode} - ${candidate.reason}`,
+      );
+    }
+  }
+  if (graph.externalEndpoints.length > 0) {
+    lines.push("External Endpoints:");
+    for (const external of graph.externalEndpoints) {
+      lines.push(
+        `${pad(1)}<${shortId(external.id)}> {${external.kind}} ${fmtSupported(external.name)}`,
+      );
+    }
+  }
+  lines.push(dumpUnresolved(graph.unresolved));
+  return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// ReqModel
+// ---------------------------------------------------------------------------
+function dumpCanonicalPath(path, depth) {
+  if (path.status === "unresolved")
+    return `\n${pad(depth)}path: ?<${shortId(path.unresolvedRef)}>`;
+  if (path.status === "unreachable") {
+    const alternates =
+      path.alternatePathRefs.length > 0
+        ? path.alternatePathRefs.map(shortId).join(", ")
+        : "none";
+    return `\n${pad(depth)}path: unreachable (alternates: ${alternates})`;
+  }
+  if (path.segments.length === 0) {
+    return `\n${pad(depth)}path (${path.reachability}): (self)`;
+  }
+  let chain = path.segments[0]?.areaName ?? "?";
+  for (const segment of path.segments) {
+    const label =
+      segment.controlName && segment.action
+        ? `${segment.controlName}: ${segment.action}`
+        : (segment.action ?? "");
+    chain += ` -[${label}]-> ${segment.targetAreaName ?? "?"}`;
+  }
+  return `\n${pad(depth)}path (${path.reachability}): ${chain}`;
+}
+function dumpReqTarget(target, depth) {
+  if (!target) return "";
+  if ("unresolvedRef" in target)
+    return `\n${pad(depth)}-> ?<${shortId(target.unresolvedRef)}>`;
+  switch (target.kind) {
+    case "area":
+      return `\n${pad(depth)}-> <${shortId(target.ref)}> ${fmtSupported(target.displayName)}`;
+    case "external":
+      return `\n${pad(depth)}-> <${shortId(target.ref)}> ${fmtSupported(target.displayName)}`;
+    case "history-back":
+      return `\n${pad(depth)}-> history-back [${target.refs.map(shortId).join(", ")}] ${fmtSupported(target.displayName)}`;
+    case "conditional-area-set": {
+      let out = `\n${pad(depth)}-> one-of ${fmtSupported(target.displayName)}`;
+      if (target.branches) {
+        for (const branch of target.branches) {
+          out += `\n${pad(depth + 1)}<${shortId(branch.ref)}>`;
+          out += fmtTextItems("when", branch.conditions, depth + 2);
+        }
+      } else {
+        out += fmtRefList("candidates", target.refs, depth + 1);
+      }
+      return out;
+    }
+    case "alternative-target-set": {
+      let out = `\n${pad(depth)}-> alternatives ${fmtSupported(target.displayName)}`;
+      for (const branch of target.branches) {
+        out += dumpReqTarget(branch.target, depth + 1);
+        out += fmtTextItems("when", branch.conditions, depth + 2);
+      }
+      return out;
+    }
+  }
+}
+function buildReqModelIndex(graph, sourceFacts, nameTraceability) {
+  return {
+    sourceFacts: buildSourceFactsIndex(sourceFacts),
+    nameTrace: nameTraceability
+      ? buildNameTraceLookup(nameTraceability.entries)
+      : undefined,
+    areasById: graph ? indexBy(graph.areas) : undefined,
+    controlsById: graph ? indexBy(graph.controls) : undefined,
+    actionsById: graph ? indexBy(graph.actions) : undefined,
+  };
+}
+function reqAreaIdentity(area, idx) {
+  const graphArea = idx.areasById?.get(area.areaRef);
+  return graphArea
+    ? areaSourceIdentity(
+        graphArea.sourceFactRefs,
+        graphArea.id,
+        idx.sourceFacts,
+        idx.nameTrace,
+      )
+    : areaSourceIdentity(
+        area.supportRefs,
+        area.areaRef,
+        idx.sourceFacts,
+        idx.nameTrace,
+      );
+}
+function reqFeatureIdentity(feature, idx) {
+  const graphControl = idx.controlsById?.get(feature.controlRef);
+  return graphControl
+    ? controlSourceIdentity(
+        graphControl.sourceFactRefs,
+        graphControl.id,
+        idx.sourceFacts,
+        idx.nameTrace,
+      )
+    : controlSourceIdentity(
+        feature.supportRefs,
+        feature.controlRef,
+        idx.sourceFacts,
+        idx.nameTrace,
+      );
+}
+/** ReqInteraction has no name-traceability coverage (only "area"/"control"
+ * entity kinds do — same as its AreaGraph Action counterpart). */
+function reqInteractionIdentity(interaction, idx) {
+  if (!idx.sourceFacts) return {};
+  const graphAction = idx.actionsById?.get(interaction.actionRef);
+  return resolveSourceIdentity(
+    graphAction?.sourceFactRefs ?? interaction.supportRefs,
+    idx.sourceFacts,
+  );
+}
+/** ReqEffectItem's own `supportRefs` is exactly the underlying Effect's
+ * `sourceFactRefs` (see analysis/req-model/build.ts's `textItem` call for
+ * "feature-effect") — already precise, no graph lookup needed. */
+function reqEffectIdentity(effect, idx) {
+  return idx.sourceFacts
+    ? resolveSourceIdentity(effect.supportRefs, idx.sourceFacts)
+    : {};
+}
+function dumpReqEffect(effect, idx, collisions, depth) {
+  const identity = reqEffectIdentity(effect, idx);
+  let out =
+    `\n${pad(depth)}<${shortId(effect.id)}> ${fmtSymbolPrefix(identity)}` +
+    `${effect.kind ? `{${effect.kind}} ` : ""}${effect.text}${fmtAnchor(identity.evidence, collisions)}`;
+  if (effect.stateKey) out += ` state=${fmtSupported(effect.stateKey)}`;
+  if (effect.value !== undefined) out += ` value=${fmtSupported(effect.value)}`;
+  return out;
+}
+function dumpReqInteraction(interaction, idx, collisions, depth) {
+  const identity = reqInteractionIdentity(interaction, idx);
+  let out =
+    `\n${pad(depth)}<${shortId(interaction.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${interaction.trigger}}${fmtAnchor(identity.evidence, collisions)}`;
+  out += fmtTextItems("conditions", interaction.conditions, depth + 1);
+  for (const effect of interaction.effects)
+    out += dumpReqEffect(effect, idx, collisions, depth + 1);
+  out += dumpReqTarget(interaction.target, depth + 1);
+  out += fmtRefList("unresolved", interaction.unresolvedRefs, depth + 1);
+  return out;
+}
+/**
+ * v1 artifacts populate only the deprecated top-level trigger/conditions/
+ * effects/target fields; synthesize one interaction so dump() still renders.
+ */
+function reqFeatureInteractions(feature) {
+  if (feature.interactions && feature.interactions.length > 0)
+    return feature.interactions;
+  return [
+    {
+      id: `${feature.id}#legacy`,
+      actionRef: feature.controlRef,
+      trigger: feature.trigger,
+      conditions: feature.conditions,
+      effects: feature.effects,
+      ...(feature.target ? { target: feature.target } : {}),
+      unresolvedRefs: feature.unresolvedRefs,
+      supportRefs: feature.supportRefs,
+    },
+  ];
+}
+function dumpReqFeature(feature, idx, collisions, depth) {
+  const identity = reqFeatureIdentity(feature, idx);
+  let out =
+    `\n${pad(depth)}<${shortId(feature.id)}> ${fmtSymbolPrefix(identity)}` +
+    `${fmtSupported(feature.displayName)}${fmtAnchor(identity.evidence, collisions)} ` +
+    `(control=<${shortId(feature.controlRef)}>)`;
+  if (feature.enabled) out += ` enabled=${fmtSupported(feature.enabled)}`;
+  if (feature.defaultValue !== undefined)
+    out += ` default=${fmtSupported(feature.defaultValue)}`;
+  out += fmtList(
+    "options",
+    feature.options.map((option) => option.value),
+    depth + 1,
+  );
+  for (const interaction of reqFeatureInteractions(feature)) {
+    out += dumpReqInteraction(interaction, idx, collisions, depth + 1);
+  }
+  return out;
+}
+function dumpReqArea(area, idx, collisions, depth) {
+  const identity = reqAreaIdentity(area, idx);
+  let out =
+    `${pad(depth)}<${shortId(area.id)}> ${fmtSymbolPrefix(identity)}` +
+    `${fmtSupported(area.displayName)}${fmtAnchor(identity.evidence, collisions)} ` +
+    `(area=<${shortId(area.areaRef)}>)`;
+  out += dumpCanonicalPath(area.canonicalPath, depth + 1);
+  out += fmtTextItems("preconditions", area.preconditions, depth + 1);
+  out += fmtTextItems("description", area.descriptionItems, depth + 1);
+  for (const feature of area.features)
+    out += dumpReqFeature(feature, idx, collisions, depth + 1);
+  out += fmtRefList("unresolved", area.unresolvedRefs, depth + 1);
+  return out;
+}
+/** Every evidence path this dump will actually render as an `@Anchor` across
+ * all ReqAreas/ReqFeatures/ReqInteractions/ReqEffectItems — same collision
+ * universe pattern as `allSourceEvidencePaths` (AreaGraph) / `dumpGapAudit`. */
+function allReqModelEvidencePaths(model, idx) {
+  const paths = [];
+  const collect = (identity) => {
+    if (identity.evidence) paths.push(identity.evidence.path);
+  };
+  for (const area of model.areas) {
+    collect(reqAreaIdentity(area, idx));
+    for (const feature of area.features) {
+      collect(reqFeatureIdentity(feature, idx));
+      for (const interaction of reqFeatureInteractions(feature)) {
+        collect(reqInteractionIdentity(interaction, idx));
+        for (const effect of interaction.effects)
+          collect(reqEffectIdentity(effect, idx));
+      }
+    }
+  }
+  return paths;
+}
+/**
+ * Dumps a ReqModelArtifact as an indented tree instead of JSON. Same Symbol/
+ * @Anchor resolution as `dumpAreaGraph`. Passing the matching area-graph.json
+ * (same run) resolves ReqArea/ReqFeature/ReqInteraction identity from the
+ * exact underlying Area/Control/Action's own `sourceFactRefs` — otherwise
+ * (area-graph.json omitted) falls back to ReqArea/ReqFeature's own broader
+ * `supportRefs`, which can occasionally pick up a nested interaction's/
+ * effect's symbol instead of the Control's own (e.g. an XML-declared Control
+ * with no JVM symbol of its own). ReqEffectItem always resolves from its own
+ * `supportRefs` (exactly the underlying Effect's `sourceFactRefs`, no graph
+ * needed). Passing the matching name-traceability.json further overrides
+ * Area/Control's Symbol/@Anchor with its precomputed, ranked identity
+ * decision when one exists (see `identityFromNameTrace`). Omitting all three,
+ * dump renders exactly as before, with no Symbol/Anchor.
+ */
+export function dumpReqModel(
+  model,
+  graph,
+  sourceFactsArtifact,
+  nameTraceability,
+) {
+  const idx = buildReqModelIndex(graph, sourceFactsArtifact, nameTraceability);
+  const collisions = collidingBasenames(allReqModelEvidencePaths(model, idx));
+  const lines = [];
+  lines.push(`ReqModel <${model.caseId}>`);
+  lines.push("Areas:");
+  for (const area of model.areas)
+    lines.push(dumpReqArea(area, idx, collisions, 1));
+  lines.push(dumpUnresolved(model.unresolved));
+  return lines.join("\n");
+}
+function fmtCounts(counts) {
+  return (
+    `observed=${counts.observed} normalized=${counts.normalized} ` +
+    `possibleGap=${counts.possibleGap} unassessed=${counts.unassessed} ` +
+    `recognized=${counts.recognized} unresolved=${counts.unresolved} ` +
+    `excludedWithReason=${counts.excludedWithReason} limited=${counts.limited}`
+  );
+}
+/** `component` facts prefer their own qualifiedName as `Symbol` (mirrors
+ * `areaSourceIdentity`); every other kind reuses the generic Control/Action/
+ * Effect resolver tiers via the fact's own id as a one-element ref list. */
+function normalizedFactIdentity(fact, idx) {
+  if (fact.kind === "component") {
+    const component = fact;
+    return {
+      symbol: component.data.qualifiedName,
+      evidence: preferredEvidence(component, idx),
+    };
+  }
+  return resolveSourceIdentity([fact.id], idx);
+}
+/** One resolved `normalizedFactRefs` entry: the real SourceFact this gap-audit
+ * candidate turned into, in the same `Symbol {kind} @Anchor` shape used
+ * everywhere else — this is what makes `normalizedFactRefs` informative
+ * instead of an opaque `fact:hash` id (its `kind` is always one of the
+ * candidate's own `expectedFactKinds` by construction, see buildCategory in
+ * analysis/gap-audit/build.ts, so `expectedFactKinds` would be redundant here).
+ * Nested directly under the candidate line with no header label — its own
+ * `<fact:id>` tag already says what it is, same convention as Area's Controls
+ * or Control's Actions. */
+function dumpNormalizedFact(ref, idx, depth, collisions) {
+  const fact = idx.factsById.get(ref);
+  if (!fact) return `\n${pad(depth)}<${shortId(ref)}>`;
+  const identity = normalizedFactIdentity(fact, idx);
+  return (
+    `\n${pad(depth)}<${shortId(fact.id)}> ${fmtSymbolPrefix(identity)}` +
+    `{${fact.kind}}${fmtAnchor(identity.evidence, collisions)}`
+  );
+}
+/** Free-text `reason`/`unassessedReason` are deliberately not rendered here:
+ * `status` (in the header tags) is the "kind of gap", and what each kind
+ * means/why is documented once in docs/dump-format.md §5.2 instead of being
+ * repeated as near-identical boilerplate prose across thousands of candidate
+ * lines (most `reason` strings are one of a handful of fixed templates from
+ * analysis/gap-audit/build.ts, not per-candidate information). The full text
+ * is still in gap-audit.json for anyone who needs the exact wording. */
+function dumpGapAuditCandidate(candidate, depth, collisions, sourceFacts) {
+  const tags = [
+    candidate.source,
+    candidate.status,
+    candidate.critical ? "critical" : undefined,
+  ].filter((tag) => tag !== undefined);
+  const symbol = candidate.evidence?.symbol;
+  const rawRecord = candidate.rawRecordRef
+    ? ` (rawRecord=<${shortId(candidate.rawRecordRef)}>)`
+    : "";
+  let out =
+    `\n${pad(depth)}<${shortId(candidate.id)}>${symbol ? ` ${symbol}` : ""} ` +
+    `{${tags.join(", ")}} "${candidate.semanticKey}"${fmtAnchor(candidate.evidence, collisions)}${rawRecord}`;
+  const resolved =
+    sourceFacts !== undefined && candidate.normalizedFactRefs.length > 0;
+  if (resolved) {
+    for (const ref of candidate.normalizedFactRefs) {
+      out += dumpNormalizedFact(ref, sourceFacts, depth + 1, collisions);
+    }
+  } else {
+    // No resolved fact to show its own {kind} — expectedFactKinds is the
+    // only kind information available, gap or not.
+    out += fmtList("expectedFactKinds", candidate.expectedFactKinds, depth + 1);
+    out += fmtRefList(
+      "normalizedFactRefs",
+      candidate.normalizedFactRefs,
+      depth + 1,
+    );
+  }
+  return out;
+}
+/** `recognized` candidates aren't gaps — they already matched a real fact
+ * (see `normalizedFacts:`) — so they sink to the bottom of each category,
+ * keeping the statuses worth a reviewer's attention (unresolved, excluded-
+ * with-reason, limited) at the top. Stable within each group: ties keep
+ * `category.candidates`' own id order (see buildCategory's final `.sort`). */
+function sortCandidatesForDump(candidates) {
+  return candidates
+    .map((candidate, index) => ({ candidate, index }))
+    .sort((left, right) => {
+      const leftRecognized = left.candidate.status === "recognized" ? 1 : 0;
+      const rightRecognized = right.candidate.status === "recognized" ? 1 : 0;
+      return leftRecognized - rightRecognized || left.index - right.index;
+    })
+    .map((entry) => entry.candidate);
+}
+function dumpGapAuditCategory(category, depth, collisions, sourceFacts) {
+  let out =
+    `${pad(depth)}<category:${category.id}> {${category.assessment}} ` +
+    `"${category.label}" (${fmtCounts(category)})`;
+  out += fmtList("expectedFactKinds", category.expectedFactKinds, depth + 1);
+  if (category.unassessedReason) {
+    out += `\n${pad(depth + 1)}unassessedReason: ${category.unassessedReason}`;
+  }
+  for (const candidate of sortCandidatesForDump(category.candidates)) {
+    out += dumpGapAuditCandidate(candidate, depth + 1, collisions, sourceFacts);
+  }
+  return out;
+}
+function dumpSemanticLimitation(limitation, depth) {
+  const tags = [
+    limitation.code,
+    limitation.critical ? "critical" : undefined,
+  ].filter((tag) => tag !== undefined);
+  let out = `${pad(depth)}<${shortId(limitation.id)}> {${tags.join(", ")}} ${limitation.message}`;
+  out += fmtRefList("candidates", limitation.candidateRefs, depth + 1);
+  out += fmtRefList("support", limitation.supportRefs, depth + 1);
+  return out;
+}
+/**
+ * Dumps a GapAuditArtifact as an indented tree instead of JSON. Passing the
+ * matching source-facts.json (same run) additionally resolves each
+ * candidate's `normalizedFactRefs` into their real Symbol/{kind}/@Anchor
+ * identity (dropping the now-redundant `expectedFactKinds` for those
+ * candidates — see `dumpNormalizedFact`); omitted, dump renders exactly as
+ * before, with bare `normalizedFactRefs: [<id>, ...]`.
+ */
+export function dumpGapAudit(audit, sourceFactsArtifact) {
+  const sourceFacts = buildSourceFactsIndex(sourceFactsArtifact);
+  const lines = [];
+  lines.push(
+    audit.target
+      ? `GapAudit <${audit.caseId}> [${audit.target.applicationModule}:${audit.target.buildVariant}]`
+      : `GapAudit <${audit.caseId}>`,
+  );
+  lines.push(
+    `Availability: xml=${audit.sourceAvailability.androidXml} ` +
+      `jvm=${audit.sourceAvailability.rawJvm} source-facts=${audit.sourceAvailability.sourceFacts}`,
+  );
+  lines.push(`Completeness: {${audit.semanticCompleteness}}`);
+  lines.push(`Summary: ${fmtCounts(audit.summary)}`);
+  const allCandidates = audit.categories.flatMap(
+    (category) => category.candidates,
+  );
+  const candidateEvidencePaths = allCandidates.flatMap((candidate) =>
+    candidate.evidence ? [candidate.evidence.path] : [],
+  );
+  // Same collision universe also covers resolved normalizedFacts' own
+  // anchors, so a shortened candidate anchor and its resolved fact's anchor
+  // never disagree on whether a given basename needed the full path.
+  const normalizedFactPaths =
+    sourceFacts === undefined
+      ? []
+      : allCandidates
+          .flatMap((candidate) => candidate.normalizedFactRefs)
+          .flatMap((ref) => {
+            const fact = sourceFacts.factsById.get(ref);
+            const evidence = fact
+              ? normalizedFactIdentity(fact, sourceFacts).evidence
+              : undefined;
+            return evidence ? [evidence.path] : [];
+          });
+  const collisions = collidingBasenames([
+    ...candidateEvidencePaths,
+    ...normalizedFactPaths,
+  ]);
+  lines.push("Categories:");
+  for (const category of audit.categories) {
+    lines.push(dumpGapAuditCategory(category, 1, collisions, sourceFacts));
+  }
+  if (audit.semanticLimitations.length === 0) {
+    lines.push("Semantic Limitations: none");
+  } else {
+    lines.push(`Semantic Limitations (${audit.semanticLimitations.length}):`);
+    for (const limitation of audit.semanticLimitations) {
+      lines.push(dumpSemanticLimitation(limitation, 1));
+    }
+  }
+  if (audit.limitations.length === 0) {
+    lines.push("Limitations: none");
+  } else {
+    lines.push("Limitations:");
+    for (const text of audit.limitations) lines.push(`${pad(1)}- ${text}`);
+  }
+  return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+/** `details` string values are near-always cross-reference ids (unresolvedRef,
+ * evidenceRefs, candidateRefs, ...) — run them through `shortId` like every
+ * other id in this dump instead of printing the full `tag:caseId/subkind/hash`
+ * (harmless no-op on the rare plain-text/non-id string, since `shortId`
+ * already passes those through unchanged). Arrays render `[a, b]` (matching
+ * `fmtRefList`'s bracket style) instead of a quoted JSON array. */
+function fmtDetailValue(value) {
+  if (typeof value === "string") return shortId(value);
+  if (Array.isArray(value)) return `[${value.map(fmtDetailValue).join(", ")}]`;
+  return JSON.stringify(value);
+}
+/** `details.impact` (present only on diagnostics derived from an
+ * UnresolvedItem, see `diagnosticsForUnresolved` in pipeline/run-stage1.ts)
+ * promoted to its own line — it is the concrete "what breaks downstream"
+ * answer, the single most debugging-relevant field `details` ever carries,
+ * so it does not belong lumped into the generic key=value dump below. */
+function detailImpact(details) {
+  const impact = details?.impact;
+  return Array.isArray(impact) &&
+    impact.every((item) => typeof item === "string")
+    ? impact
+    : [];
+}
+/** Every remaining `details` key (impact excluded, already its own line) as
+ * one key=value line — shape varies by diagnostic origin (budget numbers,
+ * gap-audit candidateRefs, unresolved's evidenceRefs, ...), genuinely
+ * per-instance debugging payload, unlike `remediation`/`disposition` (see
+ * `dumpDiagnostics`'s own doc comment for why those are omitted instead). */
+function fmtDetails(details, depth) {
+  if (!details) return "";
+  const entries = Object.entries(details).filter(([key]) => key !== "impact");
+  if (entries.length === 0) return "";
+  const line = entries
+    .map(([key, value]) => `${key}=${fmtDetailValue(value)}`)
+    .join(" ");
+  return `\n${pad(depth)}details: ${line}`;
+}
+function dumpDiagnostic(diagnostic, collisions) {
+  const tags = [
+    diagnostic.stage,
+    diagnostic.severity,
+    diagnostic.category,
+  ].join(", ");
+  const entity = diagnostic.entityKey
+    ? ` (entity=<${shortId(diagnostic.entityKey)}>)`
+    : "";
+  let out =
+    `${pad(1)}<${shortId(diagnostic.id)}> {${tags}} ${diagnostic.code}: ${diagnostic.message}` +
+    `${fmtAnchor(diagnostic.location, collisions)}${entity}`;
+  out += fmtList("impact", detailImpact(diagnostic.details), 2);
+  out += fmtDetails(diagnostic.details, 2);
+  return out;
+}
+/**
+ * Dumps a flat `Diagnostic[]` (diagnostics.json) as one line per diagnostic
+ * instead of a raw JSON array. Distinct from `dumpGapAudit`: gap-audit is a
+ * full structural census — every source candidate the analyzer looked at,
+ * recognized or not, organized by category (docs/dump-format.md §5) —
+ * while diagnostics.json is the flat, error-oriented run log actually meant
+ * to be read top to bottom. Some entries are *derived from* gap-audit's own
+ * unresolved-critical candidates (`diagnosticsForGapAudit`) or from
+ * `graph.unresolved` (`diagnosticsForUnresolved`, both in
+ * pipeline/run-stage1.ts); the rest (budget/infrastructure failures) never
+ * appear in gap-audit at all. Two JSON fields are deliberately not rendered
+ * (see docs/dump-format.md §6): `remediation` (fixed boilerplate text per
+ * `code`, not per-instance information — same reasoning as gap-audit's own
+ * `reason`/`unassessedReason`) and `disposition` (100% derivable from
+ * `severity`: "error" only ever occurs on a `fail-run` diagnostic,
+ * "info"/"warning" only on "continue" — see FailingDiagnostic/
+ * ContinuingDiagnostic in contracts/diagnostic.ts).
+ */
+export function dumpDiagnostics(diagnostics) {
+  if (diagnostics.length === 0) return "Diagnostics: none";
+  const collisions = collidingBasenames(
+    diagnostics.flatMap((diagnostic) =>
+      diagnostic.location ? [diagnostic.location.path] : [],
+    ),
+  );
+  const lines = [`Diagnostics (${diagnostics.length}):`];
+  for (const diagnostic of diagnostics)
+    lines.push(dumpDiagnostic(diagnostic, collisions));
+  return lines.join("\n");
+}