@aarwitz/tapp 0.15.0

package/mcp-server/src/release-contract.d.ts

@@ -0,0 +1,81 @@
+export type Platform = "ios" | "android" | "web";
+export type Criticality = "low" | "medium" | "high" | "critical";
+
+export interface ActorDefinition {
+  session?: "default" | "isolated" | "shared";
+  role?: string;
+  credentials?: {
+    email?: string;
+    password?: string;
+    [name: string]: string | undefined;
+  };
+  vars?: Record<string, string | number | boolean>;
+}
+
+export interface TaskContractStep<TActor extends string = string> {
+  actor: TActor;
+  task: string;
+  with?: Record<string, unknown>;
+  save?: Record<string, string>;
+  reason?: string;
+}
+
+export interface ContractExpectation {
+  screen?: string;
+  exists?: string;
+  absent?: string;
+  text?: { of: string; contains: string };
+  eventually?: { timeoutMs: number; pollMs?: number };
+}
+
+export interface ExpectContractStep<TActor extends string = string> {
+  actor: TActor;
+  expect: ContractExpectation;
+  reason?: string;
+}
+
+export interface RequestStep {
+  request: {
+    method?: string;
+    path: string;
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+  };
+}
+
+export interface ReleaseContract<TActors extends Record<string, ActorDefinition> = Record<string, ActorDefinition>> {
+  kind?: "release-contract";
+  version?: 1;
+  name: string;
+  title: string;
+  description?: string;
+  businessValue: string;
+  criticality: Criticality;
+  platforms: Platform[];
+  policy?: {
+    always?: boolean;
+    prRelevant?: boolean;
+    nightly?: boolean;
+    tags?: string[];
+  };
+  url?: string;
+  app?: string;
+  timeoutMs?: number;
+  actors: TActors;
+  variables?: Record<string, string | number | boolean>;
+  setup?: RequestStep[];
+  steps: Array<TaskContractStep<Extract<keyof TActors, string>> | ExpectContractStep<Extract<keyof TActors, string>>>;
+  teardown?: RequestStep[];
+  coverage?: {
+    nodes?: string[];
+    edges?: string[];
+    capabilities?: string[];
+    sourcePaths?: string[];
+  };
+}
+
+export declare function defineContract<const TActors extends Record<string, ActorDefinition>>(
+  contract: ReleaseContract<TActors>,
+): ReleaseContract<TActors> & { kind: "release-contract"; version: 1 };

package/mcp-server/src/release-contract.js

@@ -0,0 +1,226 @@
+// Business-level release contracts compile to the same deterministic Flow or
+// isolated Scenario runtime already used by every platform. TypeScript is an
+// authoring/type-checking surface only; it never participates in replay.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import ts from "typescript";
+import { compileFlowTasksFromRepository } from "./task-runtime.js";
+import { semanticUiKey } from "./ui-map.js";
+
+const PLATFORMS = new Set(["ios", "android", "web"]);
+const CRITICALITIES = new Set(["low", "medium", "high", "critical"]);
+const CONTRACT_AUTHORING_SPECIFIERS = new Set(["@aarwitz/tapp/contracts", "runtapp/contracts", "tapp-mcp/contracts"]);
+const CONTRACT_AUTHORING_IMPORT = /(["'])(?:@aarwitz\/tapp|runtapp|tapp-mcp)\/contracts\1/g;
+const authoringUrl = pathToFileURL(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "contract-authoring.js")).href;
+
+function expectationAction(expectation) {
+  const timeoutMs = Number(expectation.eventually?.timeoutMs || 6000);
+  if (expectation.screen) return { action: "assert_screen", target: expectation.screen, timeoutMs };
+  if (expectation.exists) return { action: "assert_exists", target: expectation.exists, timeoutMs };
+  if (expectation.absent) return { action: "assert_absent", target: expectation.absent, timeoutMs };
+  if (expectation.text) return { action: "assert_text", of: expectation.text.of, contains: expectation.text.contains, timeoutMs };
+  throw new Error("Contract expectation must define screen, exists, absent, or text");
+}
+
+function validateRequestPhases(contract, errors) {
+  for (const phase of ["setup", "teardown"]) {
+    if (contract[phase] !== undefined && !Array.isArray(contract[phase])) errors.push(`${phase} must be an array`);
+    for (const [index, step] of (contract[phase] || []).entries()) {
+      if (!step?.request || typeof step.request !== "object") errors.push(`${phase}[${index}] must be a request step`);
+      else if (!step.request.path) errors.push(`${phase}[${index}].request.path is required`);
+    }
+  }
+}
+
+export function validateReleaseContract(contract) {
+  const errors = [];
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return ["Release contract must be an object"];
+  if (contract.kind !== "release-contract") errors.push("kind must be 'release-contract'");
+  if (contract.version !== 1) errors.push("version must be 1");
+  if (!/^[a-z][A-Za-z0-9]*$/.test(String(contract.name || ""))) errors.push("name must be lower camelCase");
+  if (!String(contract.title || "").trim()) errors.push("title is required");
+  if (!String(contract.businessValue || "").trim()) errors.push("businessValue is required");
+  if (!CRITICALITIES.has(contract.criticality)) errors.push("criticality must be low|medium|high|critical");
+  if (!Array.isArray(contract.platforms) || contract.platforms.length === 0) errors.push("platforms must be a non-empty array");
+  else for (const platform of contract.platforms) if (!PLATFORMS.has(platform)) errors.push(`unsupported platform '${platform}'`);
+
+  const actorNames = contract.actors && typeof contract.actors === "object" && !Array.isArray(contract.actors)
+    ? Object.keys(contract.actors) : [];
+  if (!actorNames.length) errors.push("actors must define at least one named actor");
+  if (actorNames.length > 1) {
+    for (const actor of actorNames) if ((contract.actors[actor].session || "isolated") !== "isolated") errors.push(`actor '${actor}' must use an isolated session in a multi-actor contract`);
+  }
+
+  if (!Array.isArray(contract.steps) || contract.steps.length === 0) errors.push("steps must be a non-empty array");
+  let taskCount = 0;
+  for (const [index, step] of (contract.steps || []).entries()) {
+    if (!step || typeof step !== "object" || Array.isArray(step)) { errors.push(`steps[${index}] must be an object`); continue; }
+    if (!actorNames.includes(step.actor)) errors.push(`steps[${index}].actor must name a defined actor`);
+    if (typeof step.task === "string") {
+      taskCount += 1;
+      if (step.expect !== undefined) errors.push(`steps[${index}] cannot define both task and expect`);
+    } else if (step.expect && typeof step.expect === "object") {
+      const keys = ["screen", "exists", "absent", "text"].filter((key) => step.expect[key] !== undefined);
+      if (keys.length !== 1) errors.push(`steps[${index}].expect must define exactly one exact assertion`);
+      const eventual = step.expect.eventually;
+      if (eventual) {
+        const timeout = Number(eventual.timeoutMs);
+        const poll = Number(eventual.pollMs || 250);
+        if (!(timeout > 0 && timeout <= 120000)) errors.push(`steps[${index}].expect.eventually.timeoutMs must be 1..120000`);
+        if (!(poll >= 50 && poll <= timeout)) errors.push(`steps[${index}].expect.eventually.pollMs must be between 50 and timeoutMs`);
+      }
+    } else {
+      errors.push(`steps[${index}] must call a Task or define an exact expectation`);
+    }
+  }
+  if (!taskCount) errors.push("a release contract must compose at least one reusable Task");
+  validateRequestPhases(contract, errors);
+  return errors;
+}
+
+function rewriteAuthoringImport(source, contractPath) {
+  if (/\bimport\s*\(/.test(source) || /\brequire\s*\(/.test(source)) {
+    throw new Error("Release contracts cannot use dynamic import or require");
+  }
+  const imports = [...source.matchAll(/(?:from\s*|import\s*)["']([^"']+)["']/g)].map((match) => match[1]);
+  const unsupported = imports.filter((specifier) => !CONTRACT_AUTHORING_SPECIFIERS.has(specifier));
+  if (unsupported.length) throw new Error(`Release contract imports are limited to @aarwitz/tapp/contracts (legacy runtapp/contracts and tapp-mcp/contracts are also accepted; found ${unsupported.join(", ")})`);
+  const output = ts.transpileModule(source, {
+    fileName: contractPath,
+    compilerOptions: { module: ts.ModuleKind.ES2022, target: ts.ScriptTarget.ES2022, verbatimModuleSyntax: true },
+    reportDiagnostics: true,
+  });
+  const diagnostics = (output.diagnostics || []).filter((item) => item.category === ts.DiagnosticCategory.Error);
+  if (diagnostics.length) throw new Error(diagnostics.map((item) => ts.flattenDiagnosticMessageText(item.messageText, " ")).join("; "));
+  return output.outputText.replace(CONTRACT_AUTHORING_IMPORT, JSON.stringify(authoringUrl));
+}
+
+export async function loadReleaseContractFile(contractPath) {
+  const absolute = path.resolve(contractPath);
+  if (!fs.existsSync(absolute)) throw new Error(`Release contract not found: ${absolute}`);
+  const extension = path.extname(absolute).toLowerCase();
+  let contract;
+  if (extension === ".json") {
+    contract = JSON.parse(fs.readFileSync(absolute, "utf8"));
+  } else if ([".ts", ".mts", ".js", ".mjs"].includes(extension)) {
+    const source = fs.readFileSync(absolute, "utf8");
+    const code = extension === ".ts" || extension === ".mts" ? rewriteAuthoringImport(source, absolute)
+      : source.replace(CONTRACT_AUTHORING_IMPORT, JSON.stringify(authoringUrl));
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "tapp-contract-"));
+    const modulePath = path.join(tempDir, "contract.mjs");
+    try {
+      fs.writeFileSync(modulePath, code);
+      contract = (await import(`${pathToFileURL(modulePath).href}?v=${Date.now()}`)).default;
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  } else {
+    throw new Error("Release contracts must be .contract.ts, .mts, .mjs, .js, or .json");
+  }
+  const normalized = { ...contract, kind: contract?.kind || "release-contract", version: contract?.version ?? 1, __path: absolute };
+  const errors = validateReleaseContract(normalized);
+  if (errors.length) throw new Error(`Invalid Release Contract: ${errors.join("; ")}`);
+  return normalized;
+}
+
+function compiledActors(contract) {
+  return Object.fromEntries(Object.entries(contract.actors).map(([name, actor]) => {
+    const { credentials = {}, ...publicActor } = actor;
+    return [name, {
+      ...publicActor,
+      vars: {
+        ...(actor.vars || {}),
+        ...(credentials.email ? { EMAIL: credentials.email } : {}),
+        ...(credentials.password ? { PASSWORD: credentials.password } : {}),
+      },
+    }];
+  }));
+}
+
+export function compileReleaseContract(contract, { platform = "", sourcePath = contract.__path || "" } = {}) {
+  const errors = validateReleaseContract(contract);
+  if (errors.length) throw new Error(`Invalid Release Contract: ${errors.join("; ")}`);
+  const selected = String(platform || (contract.platforms.length === 1 ? contract.platforms[0] : "")).toLowerCase();
+  if (!selected) throw new Error("A platform is required when a release contract applies to multiple platforms");
+  if (!contract.platforms.includes(selected)) throw new Error(`Release contract '${contract.name}' does not apply to ${selected}`);
+  const actorNames = Object.keys(contract.actors);
+  if (actorNames.length > 1 && selected !== "web") throw new Error("isolated multi-actor release contracts currently run on web; iOS and Android isolation remain unsupported");
+  const multiActor = actorNames.length > 1;
+  if (!multiActor && selected !== "web" && ((contract.setup || []).length || (contract.teardown || []).length)) {
+    throw new Error("single-actor request setup/teardown currently runs on web; use target-native reset for iOS or Android");
+  }
+  const onlyActor = contract.actors[actorNames[0]];
+  const singleActorVars = multiActor ? {} : {
+    ...(onlyActor.vars || {}),
+    ...(onlyActor.credentials?.email ? { EMAIL: onlyActor.credentials.email } : {}),
+    ...(onlyActor.credentials?.password ? { PASSWORD: onlyActor.credentials.password } : {}),
+  };
+  const sourceSteps = contract.steps.map((step) => {
+    const body = step.task
+      ? { task: step.task, ...(step.with ? { with: step.with } : {}), ...(step.save ? { save: step.save } : {}) }
+      : expectationAction(step.expect);
+    return multiActor ? { actor: step.actor, do: body } : body;
+  });
+  const execution = {
+    name: contract.title,
+    kind: multiActor ? "scenario" : "flow",
+    platform: selected,
+    ...(contract.url ? { url: contract.url } : {}),
+    ...(contract.app ? { app: contract.app } : {}),
+    timeoutMs: Number(contract.timeoutMs) || 6000,
+    vars: { ...(contract.variables || {}), ...singleActorVars },
+    ...(multiActor ? { actors: compiledActors(contract) } : {}),
+    setup: contract.setup || [],
+    steps: sourceSteps,
+    teardown: contract.teardown || [],
+    releaseContract: {
+      name: contract.name,
+      title: contract.title,
+      businessValue: contract.businessValue,
+      criticality: contract.criticality,
+      policy: contract.policy || {},
+      platforms: contract.platforms,
+      coverage: contract.coverage || {},
+      source: sourcePath,
+    },
+  };
+  return compileFlowTasksFromRepository({ flow: execution, sourcePath, platform: selected });
+}
+
+function referencedNodes(contract, map) {
+  return (contract.coverage?.nodes || []).map((reference) => map.nodes.find((node) =>
+    node.id === reference || semanticUiKey(node.semanticKey) === semanticUiKey(reference) || node.name === reference)).filter(Boolean);
+}
+
+export function validateReleaseContractAgainstUiMap(contract, map) {
+  const errors = validateReleaseContract(contract);
+  const warnings = [];
+  if (!map || map.schemaVersion !== 1) return { errors: [...errors, "A UI Map v1 is required"], warnings };
+  const nodes = referencedNodes(contract, map);
+  if (nodes.length !== (contract.coverage?.nodes || []).length) errors.push("coverage.nodes contains states not present in the UI Map");
+  const edges = new Set(map.edges.map((edge) => edge.id));
+  for (const edge of contract.coverage?.edges || []) if (!edges.has(edge)) errors.push(`coverage edge '${edge}' is not present in the UI Map`);
+  if (!(contract.coverage?.nodes || []).length) warnings.push("release contract does not yet cite UI Map states");
+  return { errors, warnings };
+}
+
+export function applyReleaseContractCoverage(map, contract) {
+  const next = structuredClone(map);
+  const nodeIds = new Set(referencedNodes(contract, next).map((node) => node.id));
+  const edgeIds = new Set(contract.coverage?.edges || []);
+  next.coverage = next.coverage || { tasks: [], contracts: [], uncoveredNodeIds: [], uncoveredEdgeIds: [] };
+  next.coverage.contracts = [...new Set([...(next.coverage.contracts || []), contract.name])].sort();
+  for (const node of next.nodes) if (nodeIds.has(node.id)) {
+    node.coveredBy ||= { tasks: [], contracts: [] };
+    node.coveredBy.contracts = [...new Set([...(node.coveredBy.contracts || []), contract.name])].sort();
+  }
+  for (const edge of next.edges) if (edgeIds.has(edge.id)) {
+    edge.coveredBy ||= { tasks: [], contracts: [] };
+    edge.coveredBy.contracts = [...new Set([...(edge.coveredBy.contracts || []), contract.name])].sort();
+  }
+  next.coverage.uncoveredNodeIds = next.nodes.filter((node) => !(node.coveredBy?.tasks || []).length && !(node.coveredBy?.contracts || []).length).map((node) => node.id).sort();
+  next.coverage.uncoveredEdgeIds = next.edges.filter((edge) => !(edge.coveredBy?.tasks || []).length && !(edge.coveredBy?.contracts || []).length).map((edge) => edge.id).sort();
+  return next;
+}

package/mcp-server/src/report.js

@@ -0,0 +1,363 @@
+// Pure report/gate logic shared by the MCP server (index.js) and the CI gate CLI
+// (ci-report.js). Turns a capture's OCQA markers into the same ship/no-ship report the AutoTap
+// app produces, and diffs two runs' findings into the CI regression gate. No shell, no server —
+// keep it dependency-free so the CI path stays importable and testable.
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "../..");
+
+export function parseOcqaMarkers(markersFilePath) {
+  if (!fs.existsSync(markersFilePath)) {
+    return null;
+  }
+
+  const raw = fs.readFileSync(markersFilePath, "utf8");
+  const lines = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const counts = {
+    STATE: 0,
+    ACTION: 0,
+    TRANSITION: 0,
+    ISSUE: 0,
+    PROGRESS: 0,
+    COMPLETE: 0,
+  };
+
+  const states = [];
+  const actions = [];
+  const transitions = [];
+  const issues = [];
+  let complete = null;
+
+  for (const line of lines) {
+    if (!line.startsWith("OCQA_")) continue;
+
+    const sep = line.indexOf(":");
+    const key = sep >= 0 ? line.slice(0, sep) : line;
+    const payload = sep >= 0 ? line.slice(sep + 1).trim() : "";
+    const category = key.replace("OCQA_", "");
+
+    if (Object.prototype.hasOwnProperty.call(counts, category)) {
+      counts[category] += 1;
+    }
+
+    let parsed = payload;
+    if (payload.startsWith("{")) {
+      try {
+        parsed = JSON.parse(payload);
+      } catch {
+        parsed = payload;
+      }
+    }
+
+    if (category === "STATE") states.push(parsed);
+    if (category === "ACTION") actions.push(parsed);
+    if (category === "TRANSITION") transitions.push(parsed);
+    if (category === "ISSUE") issues.push(parsed);
+    if (category === "COMPLETE") complete = parsed;
+  }
+
+  return {
+    markersFilePath,
+    relativeMarkersFilePath: path.relative(repoRoot, markersFilePath),
+    totalLines: lines.length,
+    counts,
+    uniqueScreens: Array.from(
+      new Set(
+        states
+          .map((state) => (state && typeof state === "object" ? state.screen : null))
+          .filter((screen) => typeof screen === "string" && screen.trim().length > 0)
+      )
+    ),
+    complete,
+    recentActions: actions.slice(-5),
+    recentTransitions: transitions.slice(-5),
+    recentIssues: issues.slice(-5),
+  };
+}
+
+// Map harness OCQA_ISSUE `type` -> AutoTap FindingCategory. Crashes are always critical.
+export const ISSUE_CATEGORY = {
+  crash: "crash",
+  app_hang: "app_hang",
+  auth_failed: "auth_failure",
+  submit_failed: "unresponsive_element",
+  error_surface: "network_error_surface",
+  unresponsive_element: "unresponsive_element",
+  dead_end: "navigation_dead_end",
+  navigation_loop: "repeated_loop",
+  navigation_trap: "navigation_dead_end",
+  blank_screen: "blank_screen",
+  limited_surface: "blank_screen",
+  performance_timeout: "performance_timeout",
+  explore_timeout: "performance_timeout",
+};
+export const CRITICAL_ISSUE_TYPES = new Set(["crash"]);
+
+export function severityRank(s) {
+  return { critical: 0, high: 1, medium: 2, low: 3 }[s] ?? 4;
+}
+
+// Turn a capture's OCQA markers into the same ship/no-ship report the AutoTap app produces:
+// deduped findings + a trustworthy verdict with a coverage floor (mirrors OrchestratorService).
+export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
+  const base = parseOcqaMarkers(markersFilePath);
+  if (!base) return null;
+
+  const raw = fs.readFileSync(markersFilePath, "utf8");
+  const rawIssues = [];
+  const screens = new Set();
+  const inputsByScreen = new Map();
+  const screenElementCounts = {}; // screen -> max elements observed (content-collapse detection)
+  let anySecure = false;
+  let actions = 0;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const t = line.trim();
+    if (t.startsWith("OCQA_ISSUE:")) {
+      try {
+        const o = JSON.parse(t.slice("OCQA_ISSUE:".length));
+        let sev = String(o.severity || "medium").toLowerCase();
+        if (CRITICAL_ISSUE_TYPES.has(o.type)) sev = "critical";
+        // `target` gives a finding its identity beyond type|screen — two dead buttons on the
+        // same screen are two findings, and fixing one while breaking another is a regression.
+        const target = (typeof o.control === "string" && o.control) || (typeof o.target === "string" && o.target) || null;
+        rawIssues.push({ type: o.type, severity: sev, title: o.title, screen: o.screen || null, target, step: o.step ?? null });
+      } catch {
+        /* ignore malformed */
+      }
+    } else if (t.startsWith("OCQA_ACTION:")) {
+      actions += 1;
+    } else if (t.startsWith("OCQA_STATE:{")) {
+      try {
+        const s = JSON.parse(t.slice("OCQA_STATE:".length));
+        if (typeof s.screen === "string" && s.screen.trim()) screens.add(s.screen);
+        if (typeof s.screen === "string" && s.screen.trim() && Number.isFinite(s.elements)) {
+          screenElementCounts[s.screen] = Math.max(screenElementCounts[s.screen] || 0, s.elements);
+        }
+        if (typeof s.screen === "string" && Array.isArray(s.inputs) && s.inputs.length) {
+          const fields = s.inputs
+            .map((f) => ({ label: f.label || f.placeholder || f.key || "", secure: !!f.secure }))
+            .filter((f) => f.label);
+          if (fields.length && !inputsByScreen.has(s.screen)) inputsByScreen.set(s.screen, fields);
+          if (fields.some((f) => f.secure)) anySecure = true;
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  const inputFieldsEncountered = Array.from(inputsByScreen.entries()).map(([screen, fields]) => ({ screen, fields }));
+
+  // Dedup by stable signature (type|screen|target) so repeated detections count once —
+  // but DIFFERENT controls failing on the same screen each count.
+  const seen = new Set();
+  const findings = [];
+  for (const i of rawIssues) {
+    const key = `${i.type}|${i.screen}|${i.target ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push({ ...i, category: ISSUE_CATEGORY[i.type] || i.type });
+  }
+  findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+
+  const screensExplored = screens.size || base.uniqueScreens.length;
+  const actionsPerformed =
+    actions || (base.complete && typeof base.complete === "object" ? base.complete.actions || 0 : 0);
+  const crit = findings.filter((f) => f.severity === "critical").length;
+  const high = findings.filter((f) => f.severity === "high").length;
+  const med = findings.filter((f) => f.severity === "medium").length;
+  const low = findings.filter((f) => f.severity === "low").length;
+
+  // Coverage floor: a verdict is only trustworthy if the app was actually exercised.
+  const inconclusive = screensExplored < 2 || actionsPerformed < 3;
+  let confidence = Math.max(0, Math.min(100, 100 - crit * 25 - high * 10 - med * 3));
+  if (inconclusive) confidence = Math.min(confidence, 40);
+
+  let verdict;
+  if (crit > 0) verdict = "blocked";
+  else if (inconclusive) verdict = "caution";
+  else if (confidence < 50) verdict = "blocked";
+  else if (high > 0 || confidence < 80) verdict = "caution";
+  else verdict = "ready";
+
+  const headline = inconclusive
+    ? `Inconclusive — only ${screensExplored} screen(s) / ${actionsPerformed} action(s) explored. The app may have crashed on launch, be stuck behind a sign-in wall, or otherwise prevent exploration. Absence of issues is NOT a pass.`
+    : verdict === "ready"
+    ? "Ship-ready — no release-blocking issues found."
+    : verdict === "caution"
+    ? `Proceed with caution — ${findings.length} issue(s) to review.`
+    : `Not ready — ${findings.length} issue(s): ${crit} critical, ${high} high, ${med} medium, ${low} low.`;
+
+  // The verdict's own honesty label: exactly which defect classes this run checked, which
+  // it structurally could NOT check, and which conditions never came up — so "checked" is
+  // never claimed for a state the run didn't reach. Platform-aware: a web run doesn't
+  // inherit iOS keyboard assertions and vice versa.
+  const conditionsNotReached = [];
+  let checkedFor;
+  let notChecked;
+  if (platform === "web") {
+    checkedFor = [
+      "page errors (uncaught exceptions)", "failed/5xx requests", "broken links (404)",
+      "dead buttons", "error text on pages", "load timeouts",
+    ];
+    notChecked = [
+      "app-specific business logic (cover with Flows: record or generate, then assert)",
+      "visual correctness — layout/images/clipping (vision review; needs an API key)",
+      "only the first few visible buttons per page are probed (web beta)",
+      "content & reachability regressions require a baseline",
+    ];
+  } else if (platform === "android") {
+    checkedFor = [
+      "crashes / process exits", "dead controls", "error surfaces", "blank screens",
+      "navigation reachability", "form interaction",
+    ];
+    notChecked = [
+      "app-specific business logic (cover with committed Flows)",
+      "visual correctness — layout/images/clipping",
+      "push notifications / system integrations",
+      "content & reachability regressions require a baseline",
+    ];
+  } else {
+    checkedFor = [
+      "crashes (launch + in-run)", "hangs / stuck loading",
+      "dead controls (incl. navigation)", "error surfaces", "blank screens",
+      "navigation traps/loops", "keyboard-covered actions",
+      "lost field state (persistent-class fields)",
+    ];
+    notChecked = [
+      "app-specific business logic (cover with Flows: record or generate, then assert)",
+      "visual correctness — layout/images/clipping (vision review; needs an API key)",
+      "push notifications / system integrations",
+      "content & reachability regressions require a baseline" ,
+    ];
+  }
+  // "Failed sign-ins" is only a claim when a sign-in surface was actually encountered.
+  if (anySecure) checkedFor.splice(2, 0, "failed sign-ins");
+  else conditionsNotReached.push("sign-in (no login form encountered this run)");
+
+  return {
+    verdict,
+    // `releaseScore` is the honest name: a heuristic quality score from fixed deductions,
+    // NOT calibrated statistical confidence. `confidence` is kept as an alias for
+    // compatibility (baselines, desktop app, existing consumers).
+    confidence,
+    releaseScore: confidence,
+    headline,
+    inconclusive,
+    checkedFor,
+    notChecked,
+    conditionsNotReached,
+    platform,
+    screensExplored,
+    actionsPerformed,
+    findingCounts: { critical: crit, high, medium: med, low, total: findings.length },
+    findings,
+    screens: Array.from(screens),
+    screenElementCounts,
+    inputFieldsEncountered,
+    loginEncountered: anySecure,
+    complete: base.complete,
+    relativeMarkersFilePath: base.relativeMarkersFilePath,
+  };
+}
+
+// Content-collapse regression: screens that were rich in the baseline but are near-empty now.
+// The app "works" (renders, navigates, no errors) while its content pipeline is broken — the
+// class NO per-run detector can catch deterministically (a silent empty feed looks like a legit
+// empty state). Cross-run, it's unambiguous. Found via corpus bug-seeding: a broken API host in
+// a real HN client produced SHIP-READY 100/100 until this comparison existed.
+const COLLAPSE_MIN_BASELINE = 10; // only screens that clearly HAD content
+const COLLAPSE_RATIO = 0.4;       // current below 40% of baseline = collapsed
+export function computeContentCollapse(currentCounts, baselineCounts) {
+  if (!currentCounts || !baselineCounts) return [];
+  const findings = [];
+  for (const [screen, base] of Object.entries(baselineCounts)) {
+    const cur = currentCounts[screen];
+    if (cur === undefined || base < COLLAPSE_MIN_BASELINE) continue;
+    if (cur <= base * COLLAPSE_RATIO) {
+      findings.push({
+        type: "content_collapse",
+        severity: "high",
+        category: "content_collapse",
+        title: `Screen lost most of its content (${base} → ${cur} elements)`,
+        screen,
+        step: null,
+      });
+    }
+  }
+  return findings;
+}
+
+// Reachability-loss regression: screens the baseline explored that this run never reached
+// at all. Content-collapse can't see them (nothing to compare against) — but a screen
+// vanishing from the same-budget exploration usually means navigation regressed (a dead
+// back button trapping the explorer, a broken link, a crash short-circuiting a flow).
+// Found via subtle-bug seeding: a dead back button stranded the run on one screen and
+// SHIP-READY passed with 3 of 6 baseline screens missing. Guarded: only fires when the
+// current run had a comparable action budget (≥60% of baseline actions), so a legit
+// short run doesn't spray false losses.
+export function computeReachabilityLoss(current, baseline) {
+  if (!current?.screens || !baseline?.screens) return [];
+  const baseActions = baseline.actionsPerformed || 0;
+  if (baseActions > 0 && (current.actionsPerformed || 0) < baseActions * 0.6) return [];
+  const reached = new Set(current.screens);
+  return baseline.screens
+    .filter((s) => !reached.has(s))
+    .map((screen) => ({
+      type: "screen_unreachable",
+      severity: "high",
+      category: "navigation_dead_end",
+      title: "Screen explored in the baseline was never reached this run",
+      screen,
+      step: null,
+    }));
+}
+
+// Cross-run regression: diff this run's deduped findings against a baseline (the `findings` array a
+// prior tapp_run_qa returned), matched by the same stable signature the dedup uses (type|screen).
+// Mirrors the Swift FindingRegression.compute. Returns null when no baseline is supplied (first run).
+// The `gate` block is the CI signal: a wrapper sets a non-zero exit when gate.failed is true.
+export function computeRegression(current, baseline) {
+  if (!Array.isArray(baseline)) return null;
+  // Identity is type|screen|target when a target (control id) is known — type|screen alone
+  // would classify "Save fixed, Delete Account newly broken on Settings" as one persisting
+  // dead_button and let the new defect through the gate. Coarse matching remains as a
+  // migration fallback ONLY when one side predates target identity (old baselines), so
+  // upgrading never sprays false "new" findings.
+  const fine = (f) => `${f.type}|${f.screen ?? null}|${f.target ?? ""}`;
+  const coarse = (f) => `${f.type}|${f.screen ?? null}`;
+  const baseFine = new Set(baseline.map(fine));
+  const baseCoarseAll = new Set(baseline.map(coarse));
+  const baseCoarseNoTarget = new Set(baseline.filter((f) => f.target == null).map(coarse));
+  const currFine = new Set(current.map(fine));
+  const currCoarseAll = new Set(current.map(coarse));
+  const currCoarseNoTarget = new Set(current.filter((f) => f.target == null).map(coarse));
+
+  const currentMatches = (f) =>
+    baseFine.has(fine(f)) ||
+    (f.target == null && baseCoarseAll.has(coarse(f))) ||
+    (f.target != null && baseCoarseNoTarget.has(coarse(f)));
+  const baselineMatched = (b) =>
+    currFine.has(fine(b)) ||
+    (b.target == null && currCoarseAll.has(coarse(b))) ||
+    (b.target != null && currCoarseNoTarget.has(coarse(b)));
+
+  const newFindings = current.filter((f) => !currentMatches(f));
+  const persisting = current.filter((f) => currentMatches(f));
+  const resolved = baseline.filter((b) => !baselineMatched(b));
+  const newCritical = newFindings.filter((f) => f.severity === "critical").length;
+  const newHigh = newFindings.filter((f) => f.severity === "high").length;
+
+  return {
+    hadBaseline: true,
+    counts: { new: newFindings.length, persisting: persisting.length, resolved: resolved.length },
+    newFindings,
+    resolved,
+    // CI gate: fail the build when this run introduced new high/critical findings vs. the baseline.
+    gate: { newCritical, newHigh, failed: newCritical + newHigh > 0 },
+  };
+}