android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/analysis/gap-audit/build.js

@@ -0,0 +1,1291 @@
+import { createHash } from "node:crypto";
+import {
+  defineDiagnostic,
+  GAP_AUDIT_CONTRACT_VERSION,
+} from "../../contracts/index.js";
+import { resolveAndroidInteractionApi } from "../source-facts/android-interaction-registry.js";
+import {
+  COMPOSE_API_SEMANTIC_REGISTRY,
+  composeSourceApiName,
+  resolveComposeControlApi,
+  resolveComposePagerStateFactoryApi,
+  resolveComposePagerTransitionApi,
+  resolveComposeSurfaceApi,
+} from "../source-facts/compose-api-registry.js";
+const unsupportedComposeSurfaceApis = new Set(["Popup", "DropdownMenu"]);
+const infrastructureCallbackApis = new Map([
+  [
+    "setOnApplyWindowInsetsListener",
+    "Window-inset delivery is layout infrastructure, not a user action.",
+  ],
+  [
+    "addOnLayoutChangeListener",
+    "Layout-change delivery is rendering infrastructure, not a user action.",
+  ],
+  [
+    "addOnAttachStateChangeListener",
+    "View attachment delivery is lifecycle infrastructure, not a user action.",
+  ],
+  [
+    "setOnFocusChangeListener",
+    "Focus delivery does not by itself prove a product action.",
+  ],
+  [
+    "setOnScrollChangeListener",
+    "Scroll observation does not by itself prove a product action.",
+  ],
+  [
+    "addOnScrollListener",
+    "Scroll observation does not by itself prove a product action.",
+  ],
+  [
+    "addOnGlobalLayoutListener",
+    "Global-layout delivery is rendering infrastructure, not a user action.",
+  ],
+  [
+    "addOnPreDrawListener",
+    "Pre-draw delivery is rendering infrastructure, not a user action.",
+  ],
+  [
+    "addOnDrawListener",
+    "Draw delivery is rendering infrastructure, not a user action.",
+  ],
+  [
+    "addUpdateListener",
+    "Animation progress is presentation infrastructure, not a user action.",
+  ],
+  [
+    "withEndAction",
+    "Animation completion is presentation infrastructure, not a user action.",
+  ],
+  [
+    "doOnStart",
+    "Animation lifecycle is presentation infrastructure, not a user action.",
+  ],
+  [
+    "doOnEnd",
+    "Animation lifecycle is presentation infrastructure, not a user action.",
+  ],
+  [
+    "doOnCancel",
+    "Animation lifecycle is presentation infrastructure, not a user action.",
+  ],
+  [
+    "doOnRepeat",
+    "Animation lifecycle is presentation infrastructure, not a user action.",
+  ],
+  ["post", "Posted execution is scheduling infrastructure, not a user action."],
+  [
+    "postDelayed",
+    "Posted execution is scheduling infrastructure, not a user action.",
+  ],
+  [
+    "runOnUiThread",
+    "UI-thread dispatch is scheduling infrastructure, not a user action.",
+  ],
+  [
+    "observe",
+    "State observation is data/lifecycle infrastructure; visible uses are audited separately.",
+  ],
+  [
+    "observeForever",
+    "State observation is data/lifecycle infrastructure; visible uses are audited separately.",
+  ],
+  [
+    "addObserver",
+    "Lifecycle observation is infrastructure, not a user action.",
+  ],
+  [
+    "registerForActivityResult",
+    "Activity-result registration is callback plumbing; its launcher and result effects are normalized separately.",
+  ],
+  [
+    "enqueue",
+    "Asynchronous completion is data-flow infrastructure, not a user action.",
+  ],
+]);
+const unsupportedPagerSemanticApis = new Set([
+  "Pager",
+  "LeadingIconTab",
+  "requestScrollToPage",
+]);
+const presentationalTabLayoutApis = new Set([
+  "PrimaryTabRow",
+  "SecondaryTabRow",
+  "TabRow",
+  "ScrollableTabRow",
+]);
+const navigationApis = new Set([
+  "NavHost",
+  "composable",
+  "navigation",
+  "navigate",
+  "navigateUp",
+  "popBackStack",
+  "findNavController",
+  "startActivity",
+  "startActivityForResult",
+  "finish",
+  "finishAffinity",
+  "onBackPressed",
+]);
+const asyncApis = new Set([
+  "emit",
+  "tryEmit",
+  "collect",
+  "collectLatest",
+  "collectAsState",
+  "collectAsStateWithLifecycle",
+  "onEach",
+  "launchIn",
+  "send",
+  "trySend",
+  "receive",
+]);
+const stateObservationApis = new Set([
+  "collectAsState",
+  "collectAsStateWithLifecycle",
+]);
+const eventProducerApis = new Set(["emit", "tryEmit", "send", "trySend"]);
+const categorySpecs = [
+  {
+    id: "manifest-components",
+    label: "Manifest component declarations",
+    expectedFactKinds: ["component"],
+    producer: "android",
+  },
+  {
+    id: "manifest-entries",
+    label: "Manifest entry declarations",
+    expectedFactKinds: ["entry-point"],
+    producer: "android",
+  },
+  {
+    id: "actionable-xml-controls",
+    label: "Actionable XML controls",
+    expectedFactKinds: ["ui-element"],
+    producer: "android",
+  },
+  {
+    id: "resolved-listener-interactions",
+    label: "Android listener interactions",
+    expectedFactKinds: ["interaction-binding"],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-compose-controls",
+    label: "Compose interaction controls",
+    expectedFactKinds: ["ui-element", "interaction-binding"],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-compose-surfaces",
+    label: "Compose Area surfaces",
+    expectedFactKinds: ["component", "container-binding"],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-compose-ui",
+    label: "Other Compose UI calls",
+    expectedFactKinds: [
+      "component",
+      "ui-element",
+      "ui-property",
+      "container-binding",
+      "callback-flow",
+    ],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-navigation-calls",
+    label: "Navigation and exit calls",
+    expectedFactKinds: [
+      "component",
+      "behavior-effect",
+      "navigation-target",
+      "container-binding",
+    ],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-pager-tab-calls",
+    label: "Pager and tab calls",
+    expectedFactKinds: [
+      "component",
+      "ui-element",
+      "interaction-binding",
+      "container-binding",
+      "behavior-effect",
+      "navigation-target",
+    ],
+    producer: "jvm",
+  },
+  {
+    id: "resolved-async-calls",
+    label: "Asynchronous event-flow calls",
+    expectedFactKinds: ["callback-flow", "behavior-effect"],
+    producer: "jvm",
+  },
+  {
+    id: "other-resolved-calls",
+    label: "Calls outside the semantic census",
+    expectedFactKinds: [],
+    producer: "jvm",
+    intentionallyUnassessed: true,
+  },
+];
+function text(record, key) {
+  const value = record.data[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function sourceKind(record) {
+  const language = text(record, "language");
+  if (language === "kotlin" || record.location?.path.endsWith(".kt")) {
+    return "kotlin";
+  }
+  if (language === "java" || record.location?.path.endsWith(".java")) {
+    return "java";
+  }
+  return "other";
+}
+function rawLocation(record) {
+  if (!record.location) return undefined;
+  const startLine = Math.max(1, record.location.startLine);
+  return {
+    sourceKind: sourceKind(record),
+    path: record.location.path,
+    anchor: `raw-record:${record.id}`,
+    range: {
+      startLine,
+      endLine: Math.max(startLine, record.location.endLine),
+      ...(record.location.startColumn >= 1
+        ? { startColumn: record.location.startColumn }
+        : {}),
+      ...(record.location.endColumn >= 1
+        ? { endColumn: record.location.endColumn }
+        : {}),
+    },
+    ...(text(record, "targetSignature")
+      ? { symbol: text(record, "targetSignature") }
+      : {}),
+  };
+}
+/**
+ * The broad census and normalizers consume the same raw source locations.
+ * Columns are required when present so two calls on one line cannot credit
+ * each other with an unrelated fact.
+ */
+function locationKey(location) {
+  return JSON.stringify({
+    path: location.path
+      .trim()
+      .replaceAll("\\", "/")
+      .replace(/^\.\/+/u, "")
+      .replace(/\/{2,}/gu, "/"),
+    startLine: location.range.startLine,
+    endLine: location.range.endLine,
+    startColumn: location.range.startColumn ?? null,
+    endColumn: location.range.endColumn ?? null,
+  });
+}
+function candidateId(draft) {
+  const digest = createHash("sha256")
+    .update(
+      JSON.stringify({
+        category: draft.category,
+        source: draft.source,
+        semanticKey: draft.semanticKey,
+        evidence: draft.evidence
+          ? {
+              path: draft.evidence.path,
+              anchor: draft.evidence.anchor,
+              range: draft.evidence.range,
+              symbol: draft.evidence.symbol ?? null,
+            }
+          : null,
+        rawRecordRef: draft.rawRecordRef ?? null,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 20);
+  return `candidate:gap-audit/${draft.category}/${digest}`;
+}
+function supportIndex(source) {
+  if (!source) return new Map();
+  const evidence = new Map(source.evidence.map((item) => [item.id, item]));
+  const result = new Map();
+  for (const fact of source.facts) {
+    const keys = new Set(
+      fact.support.flatMap((support) => {
+        const location = evidence.get(support.evidenceRef);
+        return location ? [locationKey(location)] : [];
+      }),
+    );
+    for (const key of keys) {
+      const facts = result.get(key) ?? [];
+      facts.push(fact);
+      result.set(key, facts);
+    }
+  }
+  return result;
+}
+function componentDraft(component) {
+  const expectedNames = new Set([
+    component.name,
+    ...(component.targetActivity ? [component.targetActivity] : []),
+  ]);
+  return {
+    category: "manifest-components",
+    source: "android-xml",
+    semanticKey: [
+      component.kind,
+      component.name,
+      component.targetActivity ?? "",
+    ].join(":"),
+    evidence: component.evidence,
+    expectedFactKinds: ["component"],
+    matches: (fact) =>
+      fact.kind === "component" && expectedNames.has(fact.data.qualifiedName),
+    critical: true,
+    policy: "normalize",
+    manifestComponent: component,
+  };
+}
+function entryDraft(entry) {
+  return {
+    category: "manifest-entries",
+    source: "android-xml",
+    semanticKey: [
+      entry.kind,
+      entry.category,
+      entry.componentName,
+      entry.action,
+      entry.uri ?? "",
+    ].join(":"),
+    evidence: entry.evidence,
+    expectedFactKinds: ["entry-point"],
+    matches: (fact) =>
+      fact.kind === "entry-point" &&
+      fact.data.entryKind === entry.kind &&
+      fact.data.action === entry.action &&
+      fact.data.uri === entry.uri,
+    critical: true,
+    policy: "normalize",
+  };
+}
+function viewDraft(view) {
+  return {
+    category: "actionable-xml-controls",
+    source: "android-xml",
+    semanticKey: [
+      `${view.resourceType}/${view.resourceName}`,
+      view.id ?? view.tag,
+      view.onClick ?? "",
+    ].join(":"),
+    evidence: view.evidence,
+    expectedFactKinds: ["ui-element"],
+    matches: (fact) =>
+      fact.kind === "ui-element" &&
+      fact.data.actionable &&
+      (view.id === undefined || fact.data.resourceId === view.id),
+    critical: true,
+    policy: "normalize",
+  };
+}
+function apiName(bindingApi) {
+  const beforeParameters = bindingApi.split("(", 1)[0] ?? bindingApi;
+  const hash = beforeParameters.lastIndexOf("#");
+  const dot = beforeParameters.lastIndexOf(".");
+  return beforeParameters.slice(Math.max(hash, dot) + 1);
+}
+function callDraft(
+  record,
+  category,
+  expectedFactKinds,
+  critical,
+  policy,
+  matches,
+  reason,
+) {
+  const signature =
+    text(record, "targetSignature") ??
+    text(record, "targetName") ??
+    text(record, "methodName") ??
+    record.id;
+  return {
+    category,
+    source: "raw-jvm",
+    semanticKey: signature,
+    evidence: rawLocation(record),
+    rawRecordRef: record.id,
+    expectedFactKinds,
+    matches,
+    critical,
+    policy,
+    ...(reason ? { reason } : {}),
+  };
+}
+function isComposeOwner(owner) {
+  return (
+    owner.startsWith("androidx.compose.") ||
+    owner.startsWith("androidx.navigation.compose.")
+  );
+}
+function isAsyncOwner(owner) {
+  return /(?:kotlinx\.coroutines|Flow|SharedFlow|StateFlow|Channel)/u.test(
+    owner,
+  );
+}
+function isPagerTabOwner(owner) {
+  return (
+    isComposeOwner(owner) ||
+    owner.startsWith("com.google.accompanist.pager.") ||
+    /(?:^|\.)(?:Pager|PagerState|TabRow)/u.test(owner)
+  );
+}
+function registryContainsName(entries, name) {
+  return entries.some((entry) => entry.selector.apiNames.includes(name));
+}
+function isRegisteredComposeControlName(name) {
+  return registryContainsName(COMPOSE_API_SEMANTIC_REGISTRY.controls, name);
+}
+function isRegisteredComposeSurfaceName(name) {
+  return registryContainsName(COMPOSE_API_SEMANTIC_REGISTRY.surfaces, name);
+}
+function isRegisteredPagerTransitionName(name) {
+  return registryContainsName(
+    COMPOSE_API_SEMANTIC_REGISTRY.pagerTransitions,
+    name,
+  );
+}
+function isRegisteredPagerStateFactoryName(name) {
+  return registryContainsName(
+    COMPOSE_API_SEMANTIC_REGISTRY.pagerStateFactories,
+    name,
+  );
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : undefined;
+}
+function objectText(value, key) {
+  const candidate = value?.[key];
+  return typeof candidate === "string" && candidate.trim().length > 0
+    ? candidate.trim()
+    : undefined;
+}
+function eventCarrierTypes(record) {
+  const receiver = object(record.data.receiverResolvedSymbol);
+  return [
+    text(record, "targetOwnerQualifiedName"),
+    text(record, "receiverType"),
+    objectText(receiver, "type"),
+    objectText(receiver, "ownerQualifiedName"),
+    objectText(receiver, "qualifiedName"),
+  ]
+    .filter((value) => value !== undefined)
+    .join(" ");
+}
+function isExplicitEventProducer(record, name) {
+  const types = eventCarrierTypes(record);
+  if (name === "tryEmit") {
+    return /(?:Mutable)?SharedFlow/u.test(types);
+  }
+  if (name === "emit") {
+    /*
+     * An unqualified FlowCollector.emit inside flow { } is a data emission,
+     * not independently a product event. An explicitly typed SharedFlow is.
+     */
+    return (
+      /(?:Mutable)?SharedFlow/u.test(types) &&
+      Boolean(text(record, "receiverSource"))
+    );
+  }
+  return /(?:^|[.< ])(?:Channel|SendChannel)(?:[> ]|$)/u.test(types);
+}
+function isLikelyExternalComposable(owner, signature) {
+  return (
+    owner.startsWith("com.google.accompanist.") ||
+    owner.includes(".compose.") ||
+    signature.includes("androidx.compose.runtime.Composer")
+  );
+}
+function localComposableSignatures(jvm) {
+  return new Set(
+    jvm.body.flatMap((record) => {
+      if (record.kind !== "method-declaration") return [];
+      const annotations = Array.isArray(record.data.annotations)
+        ? record.data.annotations
+        : [];
+      const composable =
+        record.data.composable === true ||
+        annotations.some(
+          (annotation) =>
+            typeof annotation === "string" &&
+            /(?:^|\.)Composable$/u.test(annotation),
+        );
+      const signature = text(record, "signature");
+      return composable && signature ? [signature] : [];
+    }),
+  );
+}
+function isCallbackBinding(record) {
+  if (record.kind !== "call-argument-binding") return false;
+  const expression = object(record.data.expression);
+  const kind = text(record, "argumentKind") ?? "";
+  return (
+    record.data.isLambda === true ||
+    /^(?:lambda|callable-reference|object-literal|anonymous-class)$/u.test(
+      kind,
+    ) ||
+    objectText(expression, "callableRef") !== undefined ||
+    objectText(expression, "callableReferenceRef") !== undefined ||
+    objectText(expression, "classRef") !== undefined
+  );
+}
+function callbackCarrierText(record, bindings) {
+  const receiver = object(record.data.receiverResolvedSymbol);
+  return [
+    text(record, "targetOwnerQualifiedName"),
+    text(record, "receiverType"),
+    objectText(receiver, "type"),
+    objectText(receiver, "ownerQualifiedName"),
+    ...bindings.map((binding) => text(binding, "parameterType")),
+  ]
+    .filter((value) => value !== undefined)
+    .join(" ");
+}
+function callbackInfrastructureReason(record, name, bindings) {
+  const exact = infrastructureCallbackApis.get(name);
+  if (exact) return exact;
+  const carriers = callbackCarrierText(record, bindings);
+  if (
+    /(?:^|\.)(?:animation|transition)(?:\.|$)/iu.test(carriers) ||
+    /(?:Animator|Animation|Transition)(?:Listener|Callback)/u.test(carriers)
+  ) {
+    return "Animation or transition callbacks are presentation infrastructure, not user actions.";
+  }
+  if (
+    /(?:retrofit|okhttp|room|firebase|exoplayer|androidx\.media3|sensor|location)/iu.test(
+      carriers,
+    )
+  ) {
+    return "This callback belongs to data, media, sensor, or service infrastructure rather than a UI interaction protocol.";
+  }
+  return undefined;
+}
+function isPotentialInteractionCallback(record, name, bindings) {
+  if (!bindings.some(isCallbackBinding)) return false;
+  const conventionalName =
+    /^(?:set|add)(?:On)?[A-Za-z0-9]*(?:Listener|Callback)$/u.test(name) ||
+    /^register(?:On)?[A-Za-z0-9]*Callback$/u.test(name);
+  if (!conventionalName) return false;
+  const owner = text(record, "targetOwnerQualifiedName") ?? "";
+  if (/^(?:java|javax|kotlin|kotlinx)\./u.test(owner)) return false;
+  const carriers = callbackCarrierText(record, bindings);
+  const uiCarrier =
+    /(?:android\.(?:view|widget)|androidx\.(?:appcompat|preference|recyclerview|swiperefreshlayout|viewpager)|com\.google\.android\.material)/u.test(
+      carriers,
+    ) ||
+    /(?:View|Button|Menu|Preference|Adapter|Recycler|Pager|Tab|Search|Text|Picker|Slider|Rating|Chip|Toolbar)(?:[.$< ]|$)/u.test(
+      carriers,
+    );
+  const userEventName =
+    /(?:Click|Long|Checked|Select|Item|Menu|Query|Search|Refresh|Swipe|Drag|Touch|Submit|Preference|Rating|Tab|Page)/u.test(
+      name,
+    );
+  return uiCarrier || userEventName || owner.length > 0;
+}
+function classifyCall(record, localComposables, bindings) {
+  const rawName =
+    text(record, "targetName") ?? text(record, "methodName") ?? "";
+  const name = composeSourceApiName(rawName) ?? rawName;
+  const owner = text(record, "targetOwnerQualifiedName") ?? "";
+  const signature = text(record, "targetSignature") ?? "";
+  const composeControl = resolveComposeControlApi(owner, rawName);
+  const composeSurface = resolveComposeSurfaceApi(owner, rawName);
+  const pagerTransition = resolveComposePagerTransitionApi(owner, rawName);
+  const pagerStateFactory = resolveComposePagerStateFactoryApi(owner, rawName);
+  if (resolveAndroidInteractionApi(owner, name)) {
+    return callDraft(
+      record,
+      "resolved-listener-interactions",
+      ["interaction-binding"],
+      true,
+      "normalize",
+      (fact) =>
+        fact.kind === "interaction-binding" &&
+        apiName(fact.data.bindingApi) === name,
+    );
+  }
+  if (
+    composeSurface?.componentType === "pager" ||
+    (!owner && (name === "HorizontalPager" || name === "VerticalPager"))
+  ) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      ["component", "container-binding"],
+      true,
+      "normalize",
+      (fact) =>
+        (fact.kind === "component" &&
+          (fact.data.componentType === "pager" ||
+            fact.data.componentType === "pager-page")) ||
+        (fact.kind === "container-binding" &&
+          fact.data.bindingKind === "pager"),
+    );
+  }
+  if (composeControl?.elementType === "tab" || (!owner && name === "Tab")) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      ["ui-element", "interaction-binding"],
+      true,
+      "normalize",
+      (fact) =>
+        (fact.kind === "ui-element" && fact.data.elementType === "tab") ||
+        (fact.kind === "interaction-binding" && fact.data.trigger === "select"),
+    );
+  }
+  if (pagerTransition || (!owner && isRegisteredPagerTransitionName(name))) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      ["behavior-effect", "navigation-target"],
+      true,
+      "normalize",
+      (fact) =>
+        (fact.kind === "behavior-effect" &&
+          fact.data.effectKind === "navigate-area") ||
+        fact.kind === "navigation-target",
+    );
+  }
+  if (
+    unsupportedPagerSemanticApis.has(name) &&
+    (isPagerTabOwner(owner) || !owner)
+  ) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      categorySpecs.find((item) => item.id === "resolved-pager-tab-calls")
+        ?.expectedFactKinds ?? [],
+      true,
+      "normalize",
+      () => true,
+    );
+  }
+  if (
+    pagerStateFactory ||
+    (!owner && isRegisteredPagerStateFactoryName(name))
+  ) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      [],
+      false,
+      "exclude",
+      () => false,
+      "The Pager state factory configures a Pager; it is not independently " +
+        "a user-visible Area, control, or transition.",
+    );
+  }
+  if (
+    presentationalTabLayoutApis.has(name) &&
+    (isPagerTabOwner(owner) || !owner)
+  ) {
+    return callDraft(
+      record,
+      "resolved-pager-tab-calls",
+      [],
+      false,
+      "exclude",
+      () => false,
+      "The tab-row layout is presentational; its child Tab controls are " +
+        "audited independently.",
+    );
+  }
+  if (composeControl || (!owner && isRegisteredComposeControlName(name))) {
+    return callDraft(
+      record,
+      "resolved-compose-controls",
+      ["ui-element", "interaction-binding"],
+      true,
+      "normalize",
+      (fact) => fact.kind === "ui-element" && fact.data.actionable,
+    );
+  }
+  if (composeSurface || (!owner && isRegisteredComposeSurfaceName(name))) {
+    return callDraft(
+      record,
+      "resolved-compose-surfaces",
+      ["component", "container-binding"],
+      true,
+      "normalize",
+      (fact) => fact.kind === "component" || fact.kind === "container-binding",
+    );
+  }
+  if (
+    unsupportedComposeSurfaceApis.has(name) &&
+    (isComposeOwner(owner) || !owner)
+  ) {
+    return callDraft(
+      record,
+      "resolved-compose-surfaces",
+      ["component", "container-binding"],
+      true,
+      "normalize",
+      () => true,
+    );
+  }
+  if (
+    navigationApis.has(name) &&
+    (!owner ||
+      /(?:android|androidx\.navigation|NavController|Activity)/u.test(owner))
+  ) {
+    if (name === "findNavController") {
+      return callDraft(
+        record,
+        "resolved-navigation-calls",
+        [],
+        false,
+        "exclude",
+        () => false,
+        "findNavController resolves navigation infrastructure but does not " +
+          "perform a user-visible transition.",
+      );
+    }
+    const expectedFactKinds =
+      name === "composable"
+        ? ["component"]
+        : name === "NavHost" || name === "navigation"
+          ? ["component", "container-binding"]
+          : ["behavior-effect", "navigation-target"];
+    return callDraft(
+      record,
+      "resolved-navigation-calls",
+      expectedFactKinds,
+      true,
+      "normalize",
+      (fact) =>
+        name === "composable"
+          ? fact.kind === "component" &&
+            fact.data.componentType === "compose-destination"
+          : name === "NavHost"
+            ? fact.kind === "container-binding" &&
+              fact.data.bindingKind === "navigation"
+            : true,
+    );
+  }
+  if (asyncApis.has(name) && (!owner || isAsyncOwner(owner))) {
+    if (stateObservationApis.has(name)) {
+      return callDraft(
+        record,
+        "resolved-async-calls",
+        [],
+        false,
+        "exclude",
+        () => false,
+        "State collection bridges a Flow into Compose state; downstream " +
+          "conditions, visible UI, and controls are audited at their uses.",
+      );
+    }
+    if (eventProducerApis.has(name)) {
+      if (!isExplicitEventProducer(record, name)) {
+        return callDraft(
+          record,
+          "resolved-async-calls",
+          [],
+          false,
+          "exclude",
+          () => false,
+          "This is a data-flow emission without an explicit SharedFlow or " +
+            "Channel event carrier; downstream product behavior is audited " +
+            "at its use site.",
+        );
+      }
+      return callDraft(
+        record,
+        "resolved-async-calls",
+        ["callback-flow", "behavior-effect"],
+        true,
+        "normalize",
+        (fact) =>
+          (fact.kind === "callback-flow" &&
+            fact.data.flowKind === "event-channel") ||
+          fact.kind === "behavior-effect",
+      );
+    }
+    return callDraft(
+      record,
+      "resolved-async-calls",
+      ["callback-flow", "behavior-effect"],
+      false,
+      "recognize-or-exclude",
+      (fact) =>
+        (fact.kind === "callback-flow" &&
+          fact.data.flowKind === "event-channel") ||
+        fact.kind === "behavior-effect",
+      "The asynchronous consumer is not independently a product action; " +
+        "when it carries an event into product behavior, the event-channel " +
+        "fact recognizes it.",
+    );
+  }
+  if (signature && localComposables.has(signature)) {
+    return callDraft(
+      record,
+      "resolved-compose-ui",
+      ["component", "container-binding", "callback-flow"],
+      true,
+      "normalize",
+      () => true,
+    );
+  }
+  if (isComposeOwner(owner)) {
+    return callDraft(
+      record,
+      "resolved-compose-ui",
+      [
+        "component",
+        "ui-element",
+        "ui-property",
+        "container-binding",
+        "callback-flow",
+      ],
+      false,
+      "normalize",
+      () => true,
+    );
+  }
+  if (isLikelyExternalComposable(owner, signature)) {
+    return callDraft(
+      record,
+      "resolved-compose-ui",
+      [
+        "component",
+        "ui-element",
+        "ui-property",
+        "container-binding",
+        "callback-flow",
+      ],
+      false,
+      "limit",
+      () => true,
+      "This presentational Compose call is outside the product-critical " +
+        "semantic mapping supported by the current analyzer.",
+    );
+  }
+  if (bindings.some(isCallbackBinding)) {
+    const infrastructureReason = callbackInfrastructureReason(
+      record,
+      name,
+      bindings,
+    );
+    if (infrastructureReason) {
+      return callDraft(
+        record,
+        "resolved-listener-interactions",
+        [],
+        false,
+        "exclude",
+        () => false,
+        infrastructureReason,
+      );
+    }
+    if (isPotentialInteractionCallback(record, name, bindings)) {
+      return callDraft(
+        record,
+        "resolved-listener-interactions",
+        ["interaction-binding"],
+        false,
+        "normalize",
+        (fact) =>
+          fact.kind === "interaction-binding" &&
+          apiName(fact.data.bindingApi) === name,
+        "This callback-shaped UI protocol is not in the public Android " +
+          "interaction registry. It remains visible for custom-wrapper review.",
+      );
+    }
+  }
+  return callDraft(
+    record,
+    "other-resolved-calls",
+    [],
+    false,
+    "exclude",
+    () => false,
+    "The call is not a UI, navigation, pager/tab, listener, or asynchronous " +
+      "event-flow candidate.",
+  );
+}
+function collectDrafts(input) {
+  const drafts = [];
+  if (input.android) {
+    drafts.push(
+      ...input.android.manifest.components.map(componentDraft),
+      ...input.android.manifest.entries.map(entryDraft),
+      ...input.android.views.filter((view) => view.actionable).map(viewDraft),
+    );
+  }
+  if (input.jvm) {
+    const localComposables = localComposableSignatures(input.jvm);
+    const bindingsByCallRef = new Map();
+    for (const record of input.jvm.body) {
+      if (record.kind !== "call-argument-binding") continue;
+      const callRef = text(record, "callRef");
+      if (!callRef) continue;
+      const records = bindingsByCallRef.get(callRef) ?? [];
+      records.push(record);
+      bindingsByCallRef.set(callRef, records);
+    }
+    for (const record of input.jvm.body) {
+      if (record.kind !== "resolved-call" && record.kind !== "unresolved-call")
+        continue;
+      drafts.push(
+        classifyCall(
+          record,
+          localComposables,
+          bindingsByCallRef.get(record.id) ?? [],
+        ),
+      );
+    }
+  }
+  return drafts;
+}
+function unavailableReason(spec, input) {
+  if (spec.producer === "android" && !input.android) {
+    return "Android XML extraction was unavailable for this run.";
+  }
+  if (spec.producer === "jvm" && !input.jvm) {
+    return "Raw JVM analysis was unavailable for this run.";
+  }
+  if (spec.intentionallyUnassessed) {
+    return "Calls outside the semantic census are deliberately excluded.";
+  }
+  if (!input.source) {
+    return "Source Facts were unavailable, so normalization could not be compared.";
+  }
+  return undefined;
+}
+function componentHasExplicitAppEntry(draft, source, matchingFacts) {
+  if (!source || !draft.manifestComponent) return false;
+  const evidence = new Map(source.evidence.map((item) => [item.id, item]));
+  const componentRefs = new Set(
+    matchingFacts.flatMap((fact) =>
+      fact.kind === "component" ? [fact.id] : [],
+    ),
+  );
+  if (
+    matchingFacts.some(
+      (fact) =>
+        fact.kind === "component" &&
+        fact.support.some((support) => {
+          const kind = evidence.get(support.evidenceRef)?.sourceKind;
+          return kind === "java" || kind === "kotlin";
+        }),
+    )
+  )
+    return true;
+  return source.facts.some(
+    (fact) =>
+      (fact.kind === "navigation-target" &&
+        fact.data.targetKind === "component" &&
+        fact.data.targetKey !== undefined &&
+        componentRefs.has(fact.data.targetKey)) ||
+      (fact.kind === "behavior-effect" &&
+        fact.data.effectKind === "navigate-area" &&
+        fact.data.targetKey !== undefined &&
+        componentRefs.has(fact.data.targetKey)),
+  );
+}
+function externalAreaExclusionReason(draft, source, matchingFacts) {
+  const component = draft.manifestComponent;
+  if (
+    !component ||
+    (component.kind !== "activity" && component.kind !== "activity-alias") ||
+    component.provenance?.ownership !== "external-dependency" ||
+    componentHasExplicitAppEntry(draft, source, matchingFacts)
+  )
+    return undefined;
+  return (
+    "The Activity is injected only by an external dependency and no " +
+    "selected app/local source explicitly enters it."
+  );
+}
+function statusFor(draft, source, matchingFacts, hasEvidence) {
+  const externalReason = externalAreaExclusionReason(
+    draft,
+    source,
+    matchingFacts,
+  );
+  if (externalReason) {
+    return { status: "excluded-with-reason", reason: externalReason };
+  }
+  if (draft.policy === "exclude") {
+    return {
+      status: "excluded-with-reason",
+      reason: draft.reason ?? "The candidate is outside the semantic census.",
+    };
+  }
+  if (draft.policy === "limit") {
+    return {
+      status: "limited",
+      reason: draft.reason ?? "The candidate has limited semantic support.",
+    };
+  }
+  if (draft.policy === "recognize-or-exclude") {
+    return matchingFacts.length > 0
+      ? { status: "recognized" }
+      : {
+          status: "excluded-with-reason",
+          reason:
+            draft.reason ??
+            "The call has no independently proven product behavior.",
+        };
+  }
+  if (!source) {
+    return {
+      status: draft.critical ? "unresolved" : "limited",
+      reason: "Source Facts were unavailable for semantic comparison.",
+    };
+  }
+  if (!hasEvidence) {
+    return {
+      status: draft.critical ? "unresolved" : "limited",
+      reason:
+        "The candidate has no shared source span for semantic comparison.",
+    };
+  }
+  return matchingFacts.length > 0
+    ? { status: "recognized" }
+    : draft.critical
+      ? {
+          status: "unresolved",
+          reason: "No matching normalized Source Fact was produced.",
+        }
+      : {
+          status: "limited",
+          reason:
+            draft.reason ??
+            "No product-semantic Source Fact is available for this " +
+              "presentational UI call.",
+        };
+}
+function buildCategory(spec, drafts, input, factsByLocation) {
+  const categoryDrafts = drafts.filter((draft) => draft.category === spec.id);
+  const categoryReason = unavailableReason(spec, input);
+  const candidates = categoryDrafts
+    .map((draft) => {
+      const locationFacts = draft.evidence
+        ? (factsByLocation.get(locationKey(draft.evidence)) ?? [])
+        : [];
+      const matchingFacts = locationFacts.filter(
+        (fact) =>
+          draft.expectedFactKinds.includes(fact.kind) && draft.matches(fact),
+      );
+      const normalizedFactRefs = [
+        ...new Set(matchingFacts.map((fact) => fact.id)),
+      ].sort((left, right) => left.localeCompare(right, "en"));
+      const disposition = statusFor(
+        draft,
+        input.source,
+        matchingFacts,
+        draft.evidence !== undefined,
+      );
+      const outcome =
+        normalizedFactRefs.length > 0
+          ? "normalized"
+          : disposition.status === "unresolved" &&
+              input.source !== undefined &&
+              draft.evidence !== undefined
+            ? "possible-gap"
+            : "unassessed";
+      const unassessedReason =
+        outcome === "unassessed"
+          ? (disposition.reason ?? categoryReason)
+          : undefined;
+      return {
+        id: candidateId(draft),
+        category: draft.category,
+        source: draft.source,
+        semanticKey: draft.semanticKey,
+        ...(draft.evidence ? { evidence: draft.evidence } : {}),
+        ...(draft.rawRecordRef ? { rawRecordRef: draft.rawRecordRef } : {}),
+        expectedFactKinds: draft.expectedFactKinds,
+        normalizedFactRefs,
+        status: disposition.status,
+        critical: draft.critical,
+        ...(disposition.reason ? { reason: disposition.reason } : {}),
+        outcome,
+        ...(unassessedReason ? { unassessedReason } : {}),
+      };
+    })
+    .sort((left, right) => left.id.localeCompare(right.id, "en"));
+  const countOutcome = (outcome) =>
+    candidates.filter((candidate) => candidate.outcome === outcome).length;
+  const countStatus = (status) =>
+    candidates.filter((candidate) => candidate.status === status).length;
+  const normalized = countOutcome("normalized");
+  const possibleGap = countOutcome("possible-gap");
+  const unassessed = countOutcome("unassessed");
+  const assessed = normalized + possibleGap;
+  const assessment = categoryReason
+    ? "unassessed"
+    : unassessed === 0
+      ? "assessed"
+      : assessed > 0
+        ? "partially-assessed"
+        : "unassessed";
+  return {
+    id: spec.id,
+    label: spec.label,
+    assessment,
+    observed: candidates.length,
+    normalized,
+    possibleGap,
+    unassessed,
+    recognized: countStatus("recognized"),
+    unresolved: countStatus("unresolved"),
+    excludedWithReason: countStatus("excluded-with-reason"),
+    limited: countStatus("limited"),
+    expectedFactKinds: spec.expectedFactKinds,
+    candidates,
+    ...(categoryReason ? { unassessedReason: categoryReason } : {}),
+  };
+}
+function semanticLimitation(candidate) {
+  const critical = candidate.status === "unresolved" && candidate.critical;
+  return {
+    id: `limitation:${candidate.id.slice("candidate:".length)}`,
+    code: critical
+      ? "SEMANTIC_CANDIDATE_UNRESOLVED"
+      : "SEMANTIC_CANDIDATE_LIMITED",
+    message:
+      candidate.reason ??
+      `Semantic candidate ${candidate.semanticKey} is ${candidate.status}.`,
+    critical,
+    candidateRefs: [candidate.id],
+    supportRefs: candidate.normalizedFactRefs,
+  };
+}
+function semanticStatus(candidates) {
+  if (
+    candidates.some(
+      (candidate) => candidate.status === "unresolved" && candidate.critical,
+    )
+  )
+    return "incomplete-known";
+  if (candidates.some((candidate) => candidate.status === "limited")) {
+    return "limited";
+  }
+  return "complete";
+}
+export function buildGapAudit(input) {
+  const drafts = collectDrafts(input);
+  const factsByLocation = supportIndex(input.source);
+  const categories = categorySpecs.map((spec) =>
+    buildCategory(spec, drafts, input, factsByLocation),
+  );
+  const summary = categories.reduce(
+    (result, category) => ({
+      observed: result.observed + category.observed,
+      normalized: result.normalized + category.normalized,
+      possibleGap: result.possibleGap + category.possibleGap,
+      unassessed: result.unassessed + category.unassessed,
+      recognized: result.recognized + category.recognized,
+      unresolved: result.unresolved + category.unresolved,
+      excludedWithReason:
+        result.excludedWithReason + category.excludedWithReason,
+      limited: result.limited + category.limited,
+    }),
+    {
+      observed: 0,
+      normalized: 0,
+      possibleGap: 0,
+      unassessed: 0,
+      recognized: 0,
+      unresolved: 0,
+      excludedWithReason: 0,
+      limited: 0,
+    },
+  );
+  const candidates = categories.flatMap((category) => category.candidates);
+  const semanticLimitations = candidates
+    .filter(
+      (candidate) =>
+        candidate.status === "limited" ||
+        (candidate.status === "unresolved" && candidate.critical),
+    )
+    .map(semanticLimitation)
+    .sort((left, right) => left.id.localeCompare(right.id, "en"));
+  return {
+    contractVersion: GAP_AUDIT_CONTRACT_VERSION,
+    artifactKind: "gap-audit",
+    runId: input.runId,
+    caseId: input.caseId,
+    ...(input.target ? { target: input.target } : {}),
+    sourceAvailability: {
+      androidXml: input.android !== undefined,
+      rawJvm: input.jvm !== undefined,
+      sourceFacts: input.source !== undefined,
+    },
+    categories,
+    summary,
+    semanticCompleteness: semanticStatus(candidates),
+    semanticLimitations,
+    limitations: [
+      "The census is static and cannot observe runtime-created behavior.",
+      "excluded-with-reason candidates remain visible but do not reduce completeness.",
+      "limited is a known non-critical analyzer boundary and remains publishable.",
+    ],
+  };
+}
+function diagnosticId(category) {
+  const candidateRefs = category.candidates
+    .filter(
+      (candidate) => candidate.status === "unresolved" && candidate.critical,
+    )
+    .map((candidate) => candidate.id);
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ category: category.id, candidateRefs }))
+    .digest("hex")
+    .slice(0, 20);
+  return `diagnostic:gap-audit/${digest}`;
+}
+export function diagnosticsForGapAudit(audit) {
+  if (!audit.sourceAvailability.sourceFacts) return [];
+  return audit.categories.flatMap((category) => {
+    const candidates = category.candidates.filter(
+      (candidate) => candidate.status === "unresolved" && candidate.critical,
+    );
+    if (candidates.length === 0) return [];
+    return [
+      defineDiagnostic({
+        id: diagnosticId(category),
+        code: "STAGE1_POSSIBLE_NORMALIZATION_GAP",
+        stage: "normalize",
+        message:
+          `Gap audit found ${candidates.length} unresolved, product-significant ` +
+          `${category.label} candidate(s). Structured artifacts and the ` +
+          "deterministic draft are retained, and the quality gap remains explicit.",
+        remediation:
+          "Review the listed candidates and extend normalization or explicitly " +
+          "classify a proven non-critical boundary.",
+        ...(candidates[0]?.evidence
+          ? { location: candidates[0].evidence }
+          : {}),
+        details: {
+          category: category.id,
+          observed: category.observed,
+          normalized: category.normalized,
+          possibleGap: category.possibleGap,
+          candidateRefs: candidates.map((candidate) => candidate.id),
+        },
+        disposition: "continue",
+        severity: "warning",
+        category: "source-quality",
+      }),
+    ];
+  });
+}