Improvement #18: structured Tier-1 extractor ZIP upload errors.

Map upload Problem Details to semantic error codes with remediation copy, doc links, and Vitest coverage on the extract-upload settings page.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: joefrancisGA

archlucid-ui/src/app/(operator)/settings/extract-upload/_sections/ExtractUploadSettingsPageClient.test.tsx

@@ -0,0 +1,70 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/lib/proxy-fetch-registration-scope", () => ({
+  mergeRegistrationScopeForProxy: (init: RequestInit) => init,
+}));
+
+vi.mock("@/lib/toast", () => ({
+  showError: vi.fn(),
+  showSuccess: vi.fn(),
+}));
+
+import { ExtractUploadSettingsPageClient } from "./ExtractUploadSettingsPageClient";
+
+describe("ExtractUploadSettingsPageClient", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it("renders structured upload failure with semantic error code and doc link", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+
+      if (url.includes("workspace-baseline-artifacts") || url.includes("Get-ArchLucidAzurePackage.ps1")) {
+        return new Response("{}", { status: 404 });
+      }
+
+      if (url.includes("/v1/azure-extractor/upload") && init?.method === "POST") {
+        return new Response(
+          JSON.stringify({
+            type: "https://archlucid.net/problems/validation-failed",
+            title: "Bad Request",
+            status: 400,
+            detail: "Uploaded payload is not a valid ZIP archive.",
+            errorCode: "VALIDATION_FAILED",
+            failureKind: "archive",
+            errors: ["Uploaded payload is not a valid ZIP archive."],
+          }),
+          {
+            status: 400,
+            headers: {
+              "Content-Type": "application/json",
+              "X-Correlation-ID": "corr-upload-1",
+            },
+          },
+        );
+      }
+
+      return new Response("not found", { status: 404 });
+    });
+
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<ExtractUploadSettingsPageClient />);
+
+    const fileInput = screen.getByTestId("extract-upload-file-input");
+    const file = new File(["not-a-zip"], "broken.zip", { type: "application/zip" });
+
+    fireEvent.change(fileInput, { target: { files: [file] } });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("extract-upload-failure-callout")).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId("extract-upload-error-code")).toHaveTextContent("AZURE_EXTRACTOR_INVALID_ZIP_ARCHIVE");
+    expect(screen.getByTestId("extract-upload-troubleshooting-link")).toHaveAttribute("href", expect.stringContaining("AZURE_EXTRACTOR.md"));
+    expect(screen.getByText("Invalid ZIP archive")).toBeInTheDocument();
+  });
+});

archlucid-ui/src/app/(operator)/settings/extract-upload/_sections/ExtractUploadSettingsPageClient.tsx

@@ -11,6 +11,7 @@ import { mergeRegistrationScopeForProxy } from "@/lib/proxy-fetch-registration-s
 import { showError, showSuccess } from "@/lib/toast";
 import type { ApiProblemDetails } from "@/lib/api-problem";
 import { buildApiRequestErrorFromParts } from "@/lib/api-error";
+import { parseAzureExtractorUploadFailure } from "@/lib/azure-extractor-upload-failure";
 import { ApiV1Routes } from "@/lib/api-v1-routes";
 
 const EXTRACTOR_SCRIPT_CDN_URL =
@@ -102,7 +103,12 @@ export function ExtractUploadSettingsPageClient() {
           problem: apiError.problem,
           correlationId: apiError.correlationId ?? correlationId,
         });
-        showError("Azure upload", apiError.message);
+        const presentation = parseAzureExtractorUploadFailure(
+          apiError.problem,
+          apiError.message,
+          apiError.correlationId ?? correlationId,
+        );
+        showError("Azure upload", presentation.heading);
 
         return;
       }

archlucid-ui/src/components/AzureExtractorUploadFailureCallout.tsx

@@ -1,12 +1,14 @@
 "use client";
 
+import Link from "next/link";
 import { useCallback, useState } from "react";
 import { Copy } from "lucide-react";
 
 import { OperatorErrorCallout } from "@/components/OperatorShellMessage";
 import { Button } from "@/components/ui/button";
 import type { ApiProblemDetails } from "@/lib/api-problem";
 import { parseAzureExtractorUploadFailure } from "@/lib/azure-extractor-upload-failure";
+import { toDocsBlobUrl } from "@/lib/contextual-help-content";
 
 type AzureExtractorUploadFailureCalloutProps = {
   fallbackMessage: string;
@@ -37,8 +39,27 @@ export function AzureExtractorUploadFailureCallout(props: AzureExtractorUploadFa
   }, [copyText]);
 
   return (
-    <OperatorErrorCallout data-testid="extract-upload-failure-callout">
+    <div data-testid="extract-upload-failure-callout">
+      <OperatorErrorCallout>
       <strong>{presentation.heading}</strong>
+      <p className="mt-1 text-xs text-neutral-600 dark:text-neutral-400">
+        Error code:{" "}
+        <code
+          className="rounded bg-neutral-100 px-1 py-0.5 font-mono dark:bg-neutral-800"
+          data-testid="extract-upload-error-code"
+        >
+          {presentation.errorCode}
+        </code>
+        {presentation.apiErrorCode ? (
+          <>
+            {" "}
+            · API:{" "}
+            <code className="rounded bg-neutral-100 px-1 py-0.5 font-mono dark:bg-neutral-800">
+              {presentation.apiErrorCode}
+            </code>
+          </>
+        ) : null}
+      </p>
       <p className="mt-2">{presentation.guidance}</p>
       {presentation.errors.length > 0 ? (
         <ul className="mt-2 list-inside list-disc text-sm">
@@ -47,6 +68,17 @@ export function AzureExtractorUploadFailureCallout(props: AzureExtractorUploadFa
           ))}
         </ul>
       ) : null}
+      <p className="mt-2.5 text-sm">
+        <Link
+          href={toDocsBlobUrl(presentation.docPath)}
+          className="font-medium text-teal-800 underline underline-offset-2 dark:text-teal-300"
+          target="_blank"
+          rel="noopener noreferrer"
+          data-testid="extract-upload-troubleshooting-link"
+        >
+          Open troubleshooting guide
+        </Link>
+      </p>
       {props.correlationId ? (
         <p className="mt-2.5 text-xs text-neutral-600 dark:text-neutral-400">
           Correlation ID:{" "}
@@ -59,6 +91,7 @@ export function AzureExtractorUploadFailureCallout(props: AzureExtractorUploadFa
           {copied ? "Copied" : "Copy error details"}
         </Button>
       </div>
-    </OperatorErrorCallout>
+      </OperatorErrorCallout>
+    </div>
   );
 }

archlucid-ui/src/lib/azure-extractor-upload-error-resolver.ts

@@ -0,0 +1,169 @@
+import type { ApiProblemDetails } from "@/lib/api-problem";
+
+export type AzureExtractorUploadFailureKind = "schema" | "archive" | "validation" | "unknown";
+
+export const AZURE_EXTRACTOR_UPLOAD_DOC_PATHS = {
+  primary: "/docs/library/AZURE_EXTRACTOR.md",
+  ingestRunbook: "/docs/runbooks/AZURE_EXTRACTOR_INGEST.md",
+} as const;
+
+export type AzureExtractorUploadSemanticCode =
+  | "AZURE_EXTRACTOR_UNSUPPORTED_SCHEMA_VERSION"
+  | "AZURE_EXTRACTOR_MISSING_MANIFEST"
+  | "AZURE_EXTRACTOR_INVALID_MANIFEST_JSON"
+  | "AZURE_EXTRACTOR_MISSING_SCHEMA_VERSION"
+  | "AZURE_EXTRACTOR_MISSING_RESOURCES_JSON"
+  | "AZURE_EXTRACTOR_INVALID_ZIP_ARCHIVE"
+  | "AZURE_EXTRACTOR_RUN_SCOPE_MISMATCH"
+  | "AZURE_EXTRACTOR_ZIP_TOO_LARGE"
+  | "AZURE_EXTRACTOR_NO_FILE_UPLOADED"
+  | "AZURE_EXTRACTOR_UPLOAD_UNKNOWN";
+
+export type AzureExtractorUploadErrorResolution = {
+  semanticCode: AzureExtractorUploadSemanticCode;
+  failureKind: AzureExtractorUploadFailureKind;
+  heading: string;
+  guidance: string;
+  docPath: string;
+};
+
+function readFailureKind(problem: ApiProblemDetails | null): AzureExtractorUploadFailureKind {
+  const raw = problem?.failureKind;
+
+  if (raw === "schema" || raw === "archive" || raw === "validation") {
+    return raw;
+  }
+
+  const detail = problem?.detail?.toLowerCase() ?? "";
+
+  if (detail.includes("schemaversion") || detail.includes("manifest.json")) {
+    return "schema";
+  }
+
+  if (detail.includes("zip") || detail.includes("archive")) {
+    return "archive";
+  }
+
+  if (detail.includes("run id") || detail.includes("resources.json") || detail.includes("maximum size")) {
+    return "validation";
+  }
+
+  return "unknown";
+}
+
+function resolveSemanticCode(detail: string, failureKind: AzureExtractorUploadFailureKind): AzureExtractorUploadSemanticCode {
+  const normalized = detail.toLowerCase();
+
+  if (normalized.includes("unsupported manifest schemaversion")) {
+    return "AZURE_EXTRACTOR_UNSUPPORTED_SCHEMA_VERSION";
+  }
+
+  if (normalized.includes("does not contain manifest.json")) {
+    return "AZURE_EXTRACTOR_MISSING_MANIFEST";
+  }
+
+  if (normalized.includes("not valid json")) {
+    return "AZURE_EXTRACTOR_INVALID_MANIFEST_JSON";
+  }
+
+  if (normalized.includes("schemaversion") && normalized.includes("missing")) {
+    return "AZURE_EXTRACTOR_MISSING_SCHEMA_VERSION";
+  }
+
+  if (normalized.includes("does not contain resources.json")) {
+    return "AZURE_EXTRACTOR_MISSING_RESOURCES_JSON";
+  }
+
+  if (normalized.includes("not a valid zip archive")) {
+    return "AZURE_EXTRACTOR_INVALID_ZIP_ARCHIVE";
+  }
+
+  if (normalized.includes("run id is not recognized")) {
+    return "AZURE_EXTRACTOR_RUN_SCOPE_MISMATCH";
+  }
+
+  if (normalized.includes("exceeds maximum size")) {
+    return "AZURE_EXTRACTOR_ZIP_TOO_LARGE";
+  }
+
+  if (normalized.includes("no file uploaded")) {
+    return "AZURE_EXTRACTOR_NO_FILE_UPLOADED";
+  }
+
+  if (failureKind === "schema") {
+    return "AZURE_EXTRACTOR_MISSING_SCHEMA_VERSION";
+  }
+
+  if (failureKind === "archive") {
+    return "AZURE_EXTRACTOR_INVALID_ZIP_ARCHIVE";
+  }
+
+  return "AZURE_EXTRACTOR_UPLOAD_UNKNOWN";
+}
+
+function guidanceForSemanticCode(code: AzureExtractorUploadSemanticCode): string {
+  switch (code) {
+    case "AZURE_EXTRACTOR_UNSUPPORTED_SCHEMA_VERSION":
+      return "Re-run Get-ArchLucidAzurePackage.ps1 from the current CDN script so manifest.json uses a supported schemaVersion, then upload the new ZIP.";
+    case "AZURE_EXTRACTOR_MISSING_MANIFEST":
+      return "The ZIP must contain manifest.json at the archive root. Re-run the extractor script and upload the complete package.";
+    case "AZURE_EXTRACTOR_INVALID_MANIFEST_JSON":
+      return "manifest.json is not valid JSON. Re-run the extractor locally and confirm the file opens cleanly before uploading.";
+    case "AZURE_EXTRACTOR_MISSING_SCHEMA_VERSION":
+      return "manifest.json must include schemaVersion 1. Download the latest extractor script and regenerate the ZIP.";
+    case "AZURE_EXTRACTOR_MISSING_RESOURCES_JSON":
+      return "The ZIP must include resources.json from Get-ArchLucidAzurePackage.ps1. Do not upload a manifest-only archive.";
+    case "AZURE_EXTRACTOR_INVALID_ZIP_ARCHIVE":
+      return "Upload a complete .zip produced by Get-ArchLucidAzurePackage.ps1. Partial downloads or renamed folders often fail archive validation.";
+    case "AZURE_EXTRACTOR_RUN_SCOPE_MISMATCH":
+      return "The runId query parameter does not match a review in this workspace. Upload without runId or open the correct workspace scope first.";
+    case "AZURE_EXTRACTOR_ZIP_TOO_LARGE":
+      return "Reduce extractor scope (subscription or resource group) or use chunked upload when enabled. Confirm the ZIP is within the server size limit.";
+    case "AZURE_EXTRACTOR_NO_FILE_UPLOADED":
+      return "Select a .zip file in the upload control. The multipart form field must be named file.";
+    default:
+      return "Review the error detail, fix the extractor package, and retry. Include the copied error details when opening a support ticket.";
+  }
+}
+
+function headingForFailureKind(failureKind: AzureExtractorUploadFailureKind): string {
+  if (failureKind === "schema") {
+    return "Extractor manifest rejected";
+  }
+
+  if (failureKind === "archive") {
+    return "Invalid ZIP archive";
+  }
+
+  return "Azure extractor upload failed";
+}
+
+function docPathForSemanticCode(code: AzureExtractorUploadSemanticCode): string {
+  if (
+    code === "AZURE_EXTRACTOR_RUN_SCOPE_MISMATCH" ||
+    code === "AZURE_EXTRACTOR_ZIP_TOO_LARGE" ||
+    code === "AZURE_EXTRACTOR_NO_FILE_UPLOADED"
+  ) {
+    return AZURE_EXTRACTOR_UPLOAD_DOC_PATHS.ingestRunbook;
+  }
+
+  return AZURE_EXTRACTOR_UPLOAD_DOC_PATHS.primary;
+}
+
+/** Maps Problem Details from extractor upload endpoints into semantic codes and remediation copy. */
+export function resolveAzureExtractorUploadError(
+  problem: ApiProblemDetails | null,
+  fallbackMessage: string,
+): AzureExtractorUploadErrorResolution {
+  const failureKind = readFailureKind(problem);
+  const detail = problem?.detail?.trim() ?? fallbackMessage.trim();
+  const semanticCode = resolveSemanticCode(detail, failureKind);
+
+  return {
+    semanticCode,
+    failureKind,
+    heading: headingForFailureKind(failureKind),
+    guidance: guidanceForSemanticCode(semanticCode),
+    docPath: docPathForSemanticCode(semanticCode),
+  };
+}