android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/pipeline/run-stage1.js

@@ -0,0 +1,891 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildAreaGraph,
+  CallbackIterationBudgetExceededError,
+  CallDepthBudgetExceededError,
+  DEFAULT_MAX_CALLBACK_ITERATIONS,
+  DEFAULT_MAX_CALL_DEPTH,
+  DEFAULT_MAX_GRAPH_STATES,
+  GraphStateBudgetExceededError,
+} from "../analysis/graph/index.js";
+import {
+  buildGapAudit,
+  diagnosticsForGapAudit,
+} from "../analysis/gap-audit/index.js";
+import { buildReqModel } from "../analysis/req-model/index.js";
+import { buildSourceFacts } from "../analysis/source-facts/index.js";
+import { extractAndroidXml } from "../android/index.js";
+import {
+  defineDiagnostic,
+  RUN_CONTRACT_VERSION,
+  STAGE1_COVERAGE_VERSION,
+} from "../contracts/index.js";
+import { deriveCaseId } from "../core/stable-id.js";
+import { AnalysisFailure, hardFailure } from "../diagnostics.js";
+import { buildJvmAnalyzer, runJvmAnalysis } from "../jvm/index.js";
+import {
+  loadGradleProjectModel,
+  prepareMergedManifest,
+  selectCompatibleModuleVariant,
+  selectGradleVariant,
+} from "../project/gradle-model.js";
+import { writeDeterministicGenerationArtifacts } from "../generation/index.js";
+import { validateAreaGraph, validateReqModel } from "../validation/index.js";
+import { publishStagedArtifacts, writeJsonArtifact } from "./output.js";
+const PACKAGE_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+export const DEFAULT_ANALYSIS_LIMITS = {
+  maxCallDepth: DEFAULT_MAX_CALL_DEPTH,
+  maxCallbackIterations: DEFAULT_MAX_CALLBACK_ITERATIONS,
+  maxGraphStates: DEFAULT_MAX_GRAPH_STATES,
+};
+const SUCCESS_FILENAMES = [
+  "source-facts.json",
+  "area-graph.json",
+  "req-model.json",
+  "gap-audit.json",
+  "diagnostics.json",
+  "coverage.json",
+  "generation",
+  "run-report.json",
+];
+const FAILURE_FILENAMES = [
+  "gap-audit.json",
+  "diagnostics.json",
+  "coverage.json",
+  "run-report.json",
+];
+const STRUCTURED_FILENAMES = [
+  "source-facts.json",
+  "area-graph.json",
+  "req-model.json",
+];
+const STAGE1_PROGRESS_TOTAL = 7;
+const STAGE1_PROGRESS = {
+  projectModel: {
+    stage: "project-model",
+    index: 1,
+    label: "Load Gradle project model",
+  },
+  androidXml: {
+    stage: "android-xml",
+    index: 2,
+    label: "Merge Manifest and extract Android XML",
+  },
+  analyzerBuild: {
+    stage: "analyzer-build",
+    index: 3,
+    label: "Build JVM analyzer",
+  },
+  jvmAnalysis: {
+    stage: "jvm-analysis",
+    index: 4,
+    label: "Run JVM source analysis",
+  },
+  normalize: {
+    stage: "normalize",
+    index: 5,
+    label: "Normalize source facts",
+  },
+  graph: {
+    stage: "graph",
+    index: 6,
+    label: "Build Area graph and paths",
+  },
+  reqModel: {
+    stage: "req-model",
+    index: 7,
+    label: "Build, validate, and publish REQ model and draft",
+  },
+};
+const defaultDependencies = {
+  loadGradleProjectModel,
+  selectGradleVariant,
+  prepareMergedManifest,
+  extractAndroidXml,
+  buildJvmAnalyzer,
+  runJvmAnalysis,
+  buildSourceFacts,
+  buildAreaGraph,
+  buildReqModel,
+  validateAreaGraph,
+  validateReqModel,
+  createRunId: randomUUID,
+  now: () => new Date(),
+};
+function nonBlank(value, field) {
+  const result = value.trim();
+  if (result.length === 0) {
+    throw new Error(`${field} must not be blank`);
+  }
+  return result;
+}
+function requireNormalLauncher(android, selected) {
+  const hasNormalLauncher = android.manifest.entries.some(
+    (entry) => entry.kind === "launcher" && entry.category === "normal",
+  );
+  if (hasNormalLauncher) return;
+  throw hardFailure(
+    "NORMAL_LAUNCHER_MISSING",
+    "manifest",
+    `Selected application variant ${selected.applicationModule.gradlePath}:${selected.variant.name} has no normal Launcher entry in its merged manifest.`,
+    "Select an application variant whose merged manifest declares ACTION_MAIN with CATEGORY_LAUNCHER.",
+    {
+      applicationModule: selected.applicationModule.gradlePath,
+      buildVariant: selected.variant.name,
+      manifestPackage: android.manifest.packageName ?? "",
+      requiredEntryKind: "launcher",
+      requiredCategory: "normal",
+    },
+  );
+}
+function sortedCounts(values) {
+  const counts = {};
+  for (const value of values) {
+    counts[value] = (counts[value] ?? 0) + 1;
+  }
+  return Object.fromEntries(
+    Object.entries(counts).sort(([left], [right]) =>
+      left.localeCompare(right, "en"),
+    ),
+  );
+}
+function emptyStages() {
+  return {
+    projectModel: { complete: false },
+    androidXml: { complete: false },
+    jvm: { complete: false },
+    normalize: { complete: false },
+    graph: { complete: false },
+    reqModel: { complete: false },
+  };
+}
+function emptyCounts() {
+  return {
+    rawJvmEvents: 0,
+    rawJvmEventsByKind: {},
+    evidence: 0,
+    facts: 0,
+    factsByKind: {},
+    areas: 0,
+    controls: 0,
+    actions: 0,
+    effects: 0,
+    edges: 0,
+    entries: 0,
+    unresolved: 0,
+  };
+}
+function diagnosticId(code, stage, identity) {
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ code, stage, identity }))
+    .digest("hex")
+    .slice(0, 20);
+  return `diagnostic:stage1/${digest}`;
+}
+function unexpectedDiagnostic(error, stage) {
+  const message = error instanceof Error ? error.message : String(error);
+  return defineDiagnostic({
+    id: diagnosticId("STAGE1_UNEXPECTED_FAILURE", stage, message),
+    code: "STAGE1_UNEXPECTED_FAILURE",
+    stage,
+    message: `Stage 1 failed: ${message}`,
+    remediation:
+      "Resolve the reported source or analyzer failure and run Stage 1 again.",
+    disposition: "fail-run",
+    severity: "error",
+    category:
+      stage === "normalize" ||
+      stage === "graph" ||
+      stage === "paths" ||
+      stage === "req-model" ||
+      stage === "validate"
+        ? "invariant"
+        : "infrastructure",
+  });
+}
+function graphStateBudgetDiagnostic(error) {
+  return defineDiagnostic({
+    id: diagnosticId(
+      error.code,
+      error.stage,
+      JSON.stringify({
+        maxGraphStates: error.maxGraphStates,
+        statesUsed: error.statesUsed,
+      }),
+    ),
+    code: error.code,
+    stage: error.stage,
+    message: error.message,
+    remediation:
+      "Increase maxGraphStates or reduce the reachable Area path graph before running Stage 1 again.",
+    details: {
+      maxGraphStates: error.maxGraphStates,
+      statesUsed: error.statesUsed,
+      attemptedState: error.attemptedState,
+    },
+    disposition: "fail-run",
+    severity: "error",
+    category: "infrastructure",
+  });
+}
+function callDepthBudgetDiagnostic(error) {
+  return defineDiagnostic({
+    id: diagnosticId(
+      error.code,
+      error.stage,
+      JSON.stringify({
+        maxCallDepth: error.maxCallDepth,
+        bindingRef: error.bindingRef,
+        callbackRef: error.callbackRef,
+      }),
+    ),
+    code: error.code,
+    stage: error.stage,
+    message: error.message,
+    remediation:
+      "Increase maxCallDepth or reduce the callback-flow chain before running Stage 1 again.",
+    details: {
+      maxCallDepth: error.maxCallDepth,
+      depthReached: error.depthReached,
+      attemptedDepth: error.attemptedDepth,
+      bindingRef: error.bindingRef,
+      callbackRef: error.callbackRef,
+    },
+    disposition: "fail-run",
+    severity: "error",
+    category: "infrastructure",
+  });
+}
+function callbackIterationBudgetDiagnostic(error) {
+  return defineDiagnostic({
+    id: diagnosticId(
+      error.code,
+      error.stage,
+      JSON.stringify({
+        maxCallbackIterations: error.maxCallbackIterations,
+        bindingRef: error.bindingRef,
+        callbackRef: error.callbackRef,
+      }),
+    ),
+    code: error.code,
+    stage: error.stage,
+    message: error.message,
+    remediation:
+      "Increase maxCallbackIterations or reduce callback-flow fan-out before running Stage 1 again.",
+    details: {
+      maxCallbackIterations: error.maxCallbackIterations,
+      iterationsUsed: error.iterationsUsed,
+      attemptedIteration: error.attemptedIteration,
+      bindingRef: error.bindingRef,
+      callbackRef: error.callbackRef,
+    },
+    disposition: "fail-run",
+    severity: "error",
+    category: "infrastructure",
+  });
+}
+function diagnosticsForUnresolved(graph, source) {
+  const sourceIds = new Set(source.unresolved.map((item) => item.id));
+  return graph.unresolved
+    .map((item) => {
+      const stage = sourceIds.has(item.id) ? "normalize" : "graph";
+      return defineDiagnostic({
+        id: diagnosticId(item.reasonCode, stage, item.id),
+        code: item.reasonCode,
+        stage,
+        message: item.message,
+        entityKey: item.ownerRef,
+        details: {
+          unresolvedRef: item.id,
+          evidenceRefs: item.evidenceRefs,
+          impact: item.impact,
+        },
+        disposition: "continue",
+        severity: "warning",
+        category: "intrinsic-unknown",
+      });
+    })
+    .sort((left, right) => left.id.localeCompare(right.id, "en"));
+}
+function contextsEqual(left, right) {
+  return (
+    left.caseId === right.caseId &&
+    JSON.stringify(left.analysisContext) ===
+      JSON.stringify(right.analysisContext)
+  );
+}
+function validateArtifactSet(
+  source,
+  graph,
+  reqModel,
+  graphValidation,
+  reqValidation,
+) {
+  const issues = [...graphValidation.issues, ...reqValidation.issues];
+  if (!contextsEqual(source, graph)) {
+    issues.push({
+      code: "SOURCE_GRAPH_CONTEXT_MISMATCH",
+      path: "/analysisContext",
+      message: "Source facts and Area graph use different analysis contexts.",
+    });
+  }
+  return issues;
+}
+function updateCounts(counts, input) {
+  return {
+    ...counts,
+    ...(input.jvm
+      ? {
+          rawJvmEvents: input.jvm.document.body.length,
+          rawJvmEventsByKind: input.jvm.document.countsByKind,
+        }
+      : {}),
+    ...(input.source
+      ? {
+          evidence: input.source.evidence.length,
+          facts: input.source.facts.length,
+          factsByKind: sortedCounts(
+            input.source.facts.map((fact) => fact.kind),
+          ),
+          unresolved: input.source.unresolved.length,
+        }
+      : {}),
+    ...(input.graph
+      ? {
+          areas: input.graph.areas.length,
+          controls: input.graph.controls.length,
+          actions: input.graph.actions.length,
+          effects: input.graph.effects.length,
+          edges: input.graph.edges.length,
+          entries: input.graph.entryPoints.length,
+          unresolved: input.graph.unresolved.length,
+        }
+      : {}),
+  };
+}
+function coverageValue(input) {
+  return {
+    contractVersion: STAGE1_COVERAGE_VERSION,
+    runId: input.runId,
+    caseId: input.caseId,
+    ...(input.target ? { target: input.target } : {}),
+    stages: input.stages,
+    counts: input.counts,
+    budget: {
+      limits: input.limits,
+      exhausted: input.budgetExhausted ?? false,
+    },
+    limitations: [
+      "Only the selected Application Module, Build Variant, and Resource Configuration are represented.",
+      "Runtime-only behavior is outside this static-analysis run.",
+      "Gap audit is a conservative source census; possible-gap is the legacy count, while critical unresolved candidates drive semantic publishability.",
+    ],
+  };
+}
+async function writeCompletedOutput(outputDirectory, values) {
+  const staging = await mkdtemp(join(outputDirectory, ".stage1-publish-"));
+  try {
+    const artifacts = [];
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "source-facts.json",
+        "source-facts",
+        values.source,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "area-graph.json",
+        "area-graph",
+        values.graph,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "req-model.json",
+        "req-model",
+        values.reqModel,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "gap-audit.json",
+        "gap-audit",
+        values.gapAudit,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "diagnostics.json",
+        "diagnostics",
+        values.diagnostics,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "coverage.json",
+        "coverage",
+        values.coverage,
+      ),
+    );
+    const generated = await writeDeterministicGenerationArtifacts(
+      join(staging, "generation"),
+      {
+        source: values.source,
+        graph: values.graph,
+        reqModel: values.reqModel,
+      },
+    );
+    artifacts.push(
+      ...generated.artifacts.map((artifact) => ({
+        ...artifact,
+        relativePath: `generation/${artifact.relativePath}`,
+      })),
+    );
+    const report = {
+      ...values.reportBase,
+      completedAt: values.completedAt,
+      artifacts,
+    };
+    await writeJsonArtifact(staging, "run-report.json", "run-report", report);
+    await publishStagedArtifacts(staging, outputDirectory, SUCCESS_FILENAMES);
+    return report;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+async function writeFailedOutput(outputDirectory, values) {
+  const staging = await mkdtemp(join(outputDirectory, ".stage1-failure-"));
+  try {
+    const artifacts = [];
+    const retainedStructuredFilenames = [];
+    if (values.source) {
+      artifacts.push(
+        await writeJsonArtifact(
+          staging,
+          "source-facts.json",
+          "source-facts",
+          values.source,
+        ),
+      );
+      retainedStructuredFilenames.push("source-facts.json");
+    }
+    if (values.graph) {
+      artifacts.push(
+        await writeJsonArtifact(
+          staging,
+          "area-graph.json",
+          "area-graph",
+          values.graph,
+        ),
+      );
+      retainedStructuredFilenames.push("area-graph.json");
+    }
+    if (values.reqModel) {
+      artifacts.push(
+        await writeJsonArtifact(
+          staging,
+          "req-model.json",
+          "req-model",
+          values.reqModel,
+        ),
+      );
+      retainedStructuredFilenames.push("req-model.json");
+    }
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "gap-audit.json",
+        "gap-audit",
+        values.gapAudit,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "diagnostics.json",
+        "diagnostics",
+        values.diagnostics,
+      ),
+    );
+    artifacts.push(
+      await writeJsonArtifact(
+        staging,
+        "coverage.json",
+        "coverage",
+        values.coverage,
+      ),
+    );
+    const report = {
+      ...values.reportBase,
+      completedAt: values.completedAt,
+      artifacts,
+    };
+    await writeJsonArtifact(staging, "run-report.json", "run-report", report);
+    await publishStagedArtifacts(
+      staging,
+      outputDirectory,
+      [...retainedStructuredFilenames, ...FAILURE_FILENAMES],
+      [
+        ...STRUCTURED_FILENAMES.filter(
+          (filename) => !retainedStructuredFilenames.includes(filename),
+        ),
+        "generation",
+      ],
+    );
+    return report;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+/**
+ * Run the model-free static-analysis stage. Heavy environment boundaries are
+ * dependencies so unit tests can exercise orchestration without Gradle,
+ * Android SDKs, fixtures, a model, or a network.
+ */
+export async function runStage1(options, injected = {}) {
+  const dependencies = {
+    ...defaultDependencies,
+    ...injected,
+  };
+  const projectRoot = resolve(nonBlank(options.projectRoot, "projectRoot"));
+  const outputDirectory = resolve(
+    nonBlank(options.outputDirectory, "outputDirectory"),
+  );
+  const runId = nonBlank(options.runId ?? dependencies.createRunId(), "runId");
+  const caseId = nonBlank(
+    options.caseId ?? deriveCaseId(basename(projectRoot)),
+    "caseId",
+  );
+  const limits = options.limits ?? DEFAULT_ANALYSIS_LIMITS;
+  const startedAt = dependencies.now().toISOString();
+  const stages = emptyStages();
+  let counts = emptyCounts();
+  let target;
+  let completedStage = "configure";
+  let activeStage = "project-model";
+  let analyzerVersion = "unknown";
+  let workDirectory;
+  let androidForAudit;
+  let jvmForAudit;
+  let sourceForAudit;
+  let graphForAudit;
+  let reqModelForAudit;
+  let activeProgress;
+  const startProgress = (definition) => {
+    activeProgress = {
+      definition,
+      startedAtMs: Date.now(),
+    };
+    options.onProgress?.({
+      ...definition,
+      status: "started",
+      total: STAGE1_PROGRESS_TOTAL,
+    });
+  };
+  const finishProgress = (status) => {
+    if (!activeProgress) return;
+    const { definition, startedAtMs } = activeProgress;
+    activeProgress = undefined;
+    options.onProgress?.({
+      ...definition,
+      status,
+      total: STAGE1_PROGRESS_TOTAL,
+      elapsedMs: Date.now() - startedAtMs,
+    });
+  };
+  await mkdir(outputDirectory, { recursive: true });
+  try {
+    workDirectory = await mkdtemp(join(outputDirectory, ".stage1-work-"));
+    startProgress(STAGE1_PROGRESS.projectModel);
+    const projectModel = await dependencies.loadGradleProjectModel(
+      projectRoot,
+      {
+        initScript: resolve(
+          options.initScriptPath ??
+            join(PACKAGE_ROOT, "gradle", "reqgen-model.init.gradle"),
+        ),
+        outputPath: join(workDirectory, "gradle-project-model.json"),
+        ...(options.projectGradle ? { runner: options.projectGradle } : {}),
+      },
+    );
+    const selected = dependencies.selectGradleVariant(
+      projectModel,
+      options.applicationModulePath,
+      options.variantName,
+    );
+    const nonAndroidLocalModules = selected.reachableModules
+      .filter((module) => module.kind === "non-android-library")
+      .map((module) => module.gradlePath);
+    target = {
+      applicationModule: selected.applicationModule.gradlePath,
+      buildVariant: selected.variant.name,
+      resourceConfiguration: options.resourceConfiguration,
+      ...(nonAndroidLocalModules.length > 0 ? { nonAndroidLocalModules } : {}),
+    };
+    stages.projectModel.complete = true;
+    completedStage = "project-model";
+    finishProgress("completed");
+    activeStage = "extract";
+    startProgress(STAGE1_PROGRESS.androidXml);
+    const mergedManifestPath = await dependencies.prepareMergedManifest(
+      selected,
+      options.projectGradle,
+    );
+    const android = dependencies.extractAndroidXml({
+      selected,
+      resourceConfiguration: options.resourceConfiguration,
+      mergedManifestPath,
+    });
+    androidForAudit = android;
+    stages.androidXml.complete = true;
+    requireNormalLauncher(android, selected);
+    finishProgress("completed");
+    startProgress(STAGE1_PROGRESS.analyzerBuild);
+    const builtAnalyzer = await dependencies.buildJvmAnalyzer({
+      analyzerProjectRoot: resolve(
+        options.analyzerProjectRoot ?? join(PACKAGE_ROOT, "analyzer-jvm"),
+      ),
+      ...(options.analyzerArtifactPath
+        ? { artifactPath: options.analyzerArtifactPath }
+        : {}),
+      ...(options.analyzerGradle ? { gradle: options.analyzerGradle } : {}),
+    });
+    finishProgress("completed");
+    startProgress(STAGE1_PROGRESS.jvmAnalysis);
+    const jvm = await dependencies.runJvmAnalysis({
+      target: {
+        projectRoot,
+        applicationModulePath: selected.applicationModule.gradlePath,
+        variantName: selected.variant.name,
+        sourceRoot: projectRoot,
+      },
+      // non-android-library modules have no lintAnalyze task (no AGP applied)
+      // and contribute no source to JVM analysis — see gradle-model.ts.
+      moduleTargets: selected.reachableModules
+        .filter((module) => module.kind !== "non-android-library")
+        .map((module) => ({
+          projectRoot,
+          applicationModulePath: module.gradlePath,
+          variantName: selectCompatibleModuleVariant(module, selected.variant)
+            .name,
+          sourceRoot: projectRoot,
+        })),
+      analyzerJarPath: builtAnalyzer.jarPath,
+      outputDirectory: workDirectory,
+      ...(options.projectGradle ? { gradle: options.projectGradle } : {}),
+    });
+    jvmForAudit = jvm;
+    analyzerVersion = jvm.document.header.data.engineVersion;
+    stages.jvm.complete = true;
+    completedStage = "extract";
+    counts = updateCounts(counts, { jvm });
+    finishProgress("completed");
+    activeStage = "normalize";
+    startProgress(STAGE1_PROGRESS.normalize);
+    const sourceBase = dependencies.buildSourceFacts({
+      caseId,
+      android,
+      jvm: jvm.document,
+    });
+    sourceForAudit = sourceBase;
+    stages.normalize.complete = true;
+    completedStage = "normalize";
+    counts = updateCounts(counts, { source: sourceBase });
+    finishProgress("completed");
+    activeStage = "graph";
+    startProgress(STAGE1_PROGRESS.graph);
+    const graphBase = dependencies.buildAreaGraph(sourceBase, {
+      maxCallDepth: limits.maxCallDepth,
+      maxCallbackIterations: limits.maxCallbackIterations,
+      maxGraphStates: limits.maxGraphStates,
+    });
+    stages.graph.complete = true;
+    completedStage = "paths";
+    counts = updateCounts(counts, { graph: graphBase });
+    graphForAudit = graphBase;
+    finishProgress("completed");
+    activeStage = "req-model";
+    startProgress(STAGE1_PROGRESS.reqModel);
+    const gapAudit = buildGapAudit({
+      runId,
+      caseId,
+      target,
+      android,
+      jvm: jvm.document,
+      source: sourceBase,
+    });
+    const semanticFields = {
+      semanticCompleteness: gapAudit.semanticCompleteness,
+      limitations: gapAudit.semanticLimitations,
+    };
+    const source = {
+      ...sourceBase,
+      ...semanticFields,
+    };
+    const graph = {
+      ...graphBase,
+      ...semanticFields,
+    };
+    sourceForAudit = source;
+    graphForAudit = graph;
+    const reqModel = {
+      ...dependencies.buildReqModel(graph, source),
+      ...semanticFields,
+    };
+    reqModelForAudit = reqModel;
+    stages.reqModel.complete = true;
+    completedStage = "req-model";
+    activeStage = "validate";
+    const validationIssues = validateArtifactSet(
+      source,
+      graph,
+      reqModel,
+      dependencies.validateAreaGraph(graph),
+      dependencies.validateReqModel(reqModel, graph, source),
+    );
+    if (validationIssues.length > 0) {
+      throw new AnalysisFailure("Stage 1 artifact validation failed.", [
+        defineDiagnostic({
+          id: diagnosticId(
+            "STAGE1_ARTIFACT_VALIDATION_FAILED",
+            "validate",
+            JSON.stringify(validationIssues),
+          ),
+          code: "STAGE1_ARTIFACT_VALIDATION_FAILED",
+          stage: "validate",
+          message: "Stage 1 artifact invariants failed.",
+          remediation:
+            "Fix the analyzer or normalization invariant before publishing artifacts.",
+          details: {
+            issues: validationIssues.map((issue) => ({
+              code: issue.code,
+              path: issue.path,
+              message: issue.message,
+            })),
+          },
+          disposition: "fail-run",
+          severity: "error",
+          category: "invariant",
+        }),
+      ]);
+    }
+    completedStage = "validate";
+    const diagnostics = [
+      ...diagnosticsForUnresolved(graph, source),
+      ...diagnosticsForGapAudit(gapAudit),
+    ];
+    const coverage = coverageValue({
+      runId,
+      caseId,
+      target,
+      stages,
+      counts,
+      limits,
+    });
+    const completedAt = dependencies.now().toISOString();
+    const publishable = gapAudit.semanticCompleteness !== "incomplete-known";
+    const report = await writeCompletedOutput(outputDirectory, {
+      source,
+      graph,
+      reqModel,
+      gapAudit,
+      diagnostics,
+      coverage,
+      completedAt,
+      reportBase: {
+        contractVersion: RUN_CONTRACT_VERSION,
+        runId,
+        caseId,
+        target,
+        analyzerVersion,
+        startedAt,
+        diagnostics,
+        semanticCompleteness: gapAudit.semanticCompleteness,
+        status: "succeeded",
+        publishable,
+        completedStage: "validate",
+      },
+    });
+    finishProgress("completed");
+    return { report, coverage, outputDirectory };
+  } catch (error) {
+    finishProgress("failed");
+    const budgetExhausted =
+      error instanceof GraphStateBudgetExceededError ||
+      error instanceof CallDepthBudgetExceededError ||
+      error instanceof CallbackIterationBudgetExceededError;
+    const failureDiagnostics =
+      error instanceof GraphStateBudgetExceededError
+        ? [graphStateBudgetDiagnostic(error)]
+        : error instanceof CallDepthBudgetExceededError
+          ? [callDepthBudgetDiagnostic(error)]
+          : error instanceof CallbackIterationBudgetExceededError
+            ? [callbackIterationBudgetDiagnostic(error)]
+            : error instanceof AnalysisFailure
+              ? error.diagnostics
+              : [unexpectedDiagnostic(error, activeStage)];
+    const gapAudit = buildGapAudit({
+      runId,
+      caseId,
+      ...(target ? { target } : {}),
+      ...(androidForAudit ? { android: androidForAudit } : {}),
+      ...(jvmForAudit ? { jvm: jvmForAudit.document } : {}),
+      ...(sourceForAudit ? { source: sourceForAudit } : {}),
+    });
+    const diagnostics = [
+      ...failureDiagnostics,
+      ...diagnosticsForGapAudit(gapAudit),
+    ];
+    const coverage = coverageValue({
+      runId,
+      caseId,
+      ...(target ? { target } : {}),
+      stages,
+      counts,
+      limits,
+      budgetExhausted,
+    });
+    const completedAt = dependencies.now().toISOString();
+    const report = await writeFailedOutput(outputDirectory, {
+      ...(sourceForAudit ? { source: sourceForAudit } : {}),
+      ...(graphForAudit ? { graph: graphForAudit } : {}),
+      ...(reqModelForAudit ? { reqModel: reqModelForAudit } : {}),
+      gapAudit,
+      diagnostics,
+      coverage,
+      completedAt,
+      reportBase: {
+        contractVersion: RUN_CONTRACT_VERSION,
+        runId,
+        caseId,
+        ...(target ? { target } : {}),
+        analyzerVersion,
+        startedAt,
+        diagnostics,
+        semanticCompleteness: "incomplete-known",
+        status: "failed",
+        publishable: false,
+        ...(completedStage ? { completedStage } : {}),
+      },
+    });
+    return { report, coverage, outputDirectory };
+  } finally {
+    if (workDirectory) {
+      await rm(workDirectory, { recursive: true, force: true });
+    }
+  }
+}