feat: structured errorKind on ProviderReport for federation diagnostics

- Add ErrorKind enum (ok | timeout | http-4xx | http-5xx | network | decode | rate-limited) to types.ts
- Extend ProviderReport with optional errorKind + errorContext fields (back-compat additive)
- Wire errorKind in federation.ts: classifyError() inspects AbortSignal + HTTP status
  (from .status/.statusCode properties and 'HTTP NNN' message patterns) + decode heuristics
- extractHttpContext() captures httpStatus into errorContext for 4xx/5xx reports
- Happy path sets errorKind='ok'
- 7 new tests: ok, timeout, http-4xx/404, http-5xx/500, rate-limited/429, network, decode
- Update providers.new.test.ts snapshot to include errorKind: 'network'

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: masonwyatt23

packages/core/src/federation.ts

@@ -15,6 +15,7 @@ import { buildAttribution } from "./license.ts";
 import { rankAll } from "./pick.ts";
 import { ALL_PROVIDERS, DEFAULT_PROVIDERS } from "./providers/index.ts";
 import type {
+  ErrorKind,
   ImageCandidate,
   Provider,
   ProviderId,
@@ -97,17 +98,17 @@ async function runProvider(
 ): Promise<ImageCandidate[]> {
   const provider: Provider | undefined = ALL_PROVIDERS[id];
   if (!provider) {
-    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, error: "unknown provider" });
+    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, error: "unknown provider", errorKind: "network" });
     return [];
   }
   // Opt-in providers that weren't requested explicitly are never run (already
   // filtered out in DEFAULT_PROVIDERS, but guard anyway).
   if (provider.optIn && !(opts.providers ?? []).includes(id)) {
-    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, skipped: "not-enabled" });
+    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, skipped: "not-enabled", errorKind: "network" });
     return [];
   }
   if (!providerCanRun(provider, opts)) {
-    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, skipped: "missing-auth" });
+    reports.push({ provider: id, ok: false, count: 0, timeMs: 0, skipped: "missing-auth", errorKind: "network" });
     return [];
   }
 
@@ -123,16 +124,21 @@ async function runProvider(
 
   try {
     const out = await provider.search(query, providerOpts);
-    reports.push({ provider: id, ok: true, count: out.length, timeMs: Date.now() - started });
+    reports.push({ provider: id, ok: true, count: out.length, timeMs: Date.now() - started, errorKind: "ok" });
     return out;
   } catch (e) {
+    const elapsed = Date.now() - started;
     const msg = (e as Error).message ?? "unknown";
+    const kind = classifyError(e, ctl.signal.aborted);
+    const ctx = kind === "http-4xx" || kind === "http-5xx" ? extractHttpContext(e) : undefined;
     reports.push({
       provider: id,
       ok: false,
       count: 0,
-      timeMs: Date.now() - started,
+      timeMs: elapsed,
       error: msg,
+      errorKind: kind,
+      ...(ctx ? { errorContext: ctx } : {}),
     });
     return [];
   } finally {
@@ -141,6 +147,41 @@ async function runProvider(
   }
 }
 
+/** Map a caught error to a structured ErrorKind. */
+function classifyError(e: unknown, timedOut: boolean): ErrorKind {
+  if (timedOut) return "timeout";
+  const msg = (e as Error)?.message ?? "";
+  // HTTP errors surfaced by providers as Error with status embedded in message.
+  // Convention: providers throw `new Error("HTTP 429 …")` etc.
+  const statusMatch = msg.match(/\bHTTP\s+(\d{3})\b/i) ?? msg.match(/\bstatus[:\s]+(\d{3})\b/i);
+  if (statusMatch) {
+    const status = Number(statusMatch[1]);
+    if (status === 429) return "rate-limited";
+    if (status >= 400 && status < 500) return "http-4xx";
+    if (status >= 500) return "http-5xx";
+  }
+  // Providers may also attach a .status property directly.
+  const status = (e as any)?.status ?? (e as any)?.statusCode;
+  if (typeof status === "number") {
+    if (status === 429) return "rate-limited";
+    if (status >= 400 && status < 500) return "http-4xx";
+    if (status >= 500) return "http-5xx";
+  }
+  // JSON / schema parse failures.
+  if (msg.includes("JSON") || msg.includes("parse") || msg.includes("unexpected token")) {
+    return "decode";
+  }
+  return "network";
+}
+
+/** Pull HTTP status into errorContext when available. */
+function extractHttpContext(e: unknown): Record<string, unknown> | undefined {
+  const msg = (e as Error)?.message ?? "";
+  const statusFromMsg = msg.match(/\bHTTP\s+(\d{3})\b/i)?.[1] ?? msg.match(/\bstatus[:\s]+(\d{3})\b/i)?.[1];
+  const status = (e as any)?.status ?? (e as any)?.statusCode ?? (statusFromMsg ? Number(statusFromMsg) : undefined);
+  return status !== undefined ? { httpStatus: status } : undefined;
+}
+
 function providerCanRun(provider: Provider, opts: SearchOptions): boolean {
   if (!provider.requiresAuth) return true;
   const req = provider.auth;

packages/core/src/types.ts

@@ -85,13 +85,31 @@ export interface ImageCandidate {
   viaBrowserFallback?: boolean;
 }
 
+/**
+ * Structured reason for a provider outcome.
+ * "ok" is set on success; all other values indicate failure/skip categories.
+ * Optional — callers that don't care can ignore it; shape remains back-compat.
+ */
+export type ErrorKind =
+  | "ok"
+  | "timeout"
+  | "http-4xx"
+  | "http-5xx"
+  | "network"
+  | "decode"
+  | "rate-limited";
+
 export interface ProviderReport {
   provider: ProviderId;
   ok: boolean;
   count: number;
   timeMs: number;
   error?: string;
   skipped?: "missing-auth" | "disabled" | "rate-limited" | "not-enabled";
+  /** Structured failure category. Allows callers/agents to route on WHY a provider failed. */
+  errorKind?: ErrorKind;
+  /** Additional diagnostic context (e.g. HTTP status code, decode field). */
+  errorContext?: Record<string, unknown>;
 }
 
 export interface SearchOptions {

tests/federation.test.ts

@@ -60,4 +60,122 @@ describe("federation", () => {
     const failed = out.providerReports.find((r) => r.provider === "openverse");
     expect(failed?.ok).toBe(false);
   });
+
+  test("errorKind=ok on successful provider", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => jsonResponse(fixture("wikimedia.json")),
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(true);
+    expect(report?.errorKind).toBe("ok");
+  });
+
+  test("errorKind=timeout when provider aborts due to timeout", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async (_url, init) =>
+          new Promise((_resolve, reject) => {
+            // Simulate an async operation that respects the abort signal
+            const signal = init?.signal as AbortSignal | undefined;
+            if (signal?.aborted) {
+              reject(Object.assign(new Error("The operation was aborted"), { name: "AbortError" }));
+              return;
+            }
+            signal?.addEventListener("abort", () => {
+              reject(Object.assign(new Error("The operation was aborted"), { name: "AbortError" }));
+            });
+          }),
+      },
+    ]);
+    const out = await searchImages("test", {
+      providers: ["wikimedia"],
+      fetcher,
+      timeoutMs: 10, // very short — will fire before the never-resolving promise
+    });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("timeout");
+  });
+
+  test("errorKind=http-4xx for 404 response", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => {
+          throw Object.assign(new Error("HTTP 404 Not Found"), { status: 404 });
+        },
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("http-4xx");
+    expect(report?.errorContext?.httpStatus).toBe(404);
+  });
+
+  test("errorKind=http-5xx for 500 response thrown as error", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => {
+          throw Object.assign(new Error("HTTP 500 Internal Server Error"), { status: 500 });
+        },
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("http-5xx");
+    expect(report?.errorContext?.httpStatus).toBe(500);
+  });
+
+  test("errorKind=rate-limited for 429 response", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => {
+          throw Object.assign(new Error("HTTP 429 Too Many Requests"), { status: 429 });
+        },
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("rate-limited");
+  });
+
+  test("errorKind=network for generic fetch failure", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => {
+          throw new Error("fetch failed: ECONNREFUSED");
+        },
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("network");
+  });
+
+  test("errorKind=decode for JSON parse failure", async () => {
+    const fetcher = stubFetcher([
+      {
+        match: (u) => u.includes("commons.wikimedia.org"),
+        handler: async () => {
+          throw new Error("Unexpected token < in JSON at position 0");
+        },
+      },
+    ]);
+    const out = await searchImages("test", { providers: ["wikimedia"], fetcher });
+    const report = out.providerReports.find((r) => r.provider === "wikimedia");
+    expect(report?.ok).toBe(false);
+    expect(report?.errorKind).toBe("decode");
+  });
 });

tests/providers.new.test.ts

@@ -102,6 +102,7 @@ describe("provider auth contracts", () => {
             count: 0,
             timeMs: 0,
             skipped: "missing-auth",
+            errorKind: "network",
           },
         ]);
       }