feat(metadata): add fetch pipeline diagnostics

The metadata fetch pipeline now gathers and returns detailed diagnostics
about provider selection, candidate results, and the reason for empty
resolved fields (e.g. no active providers, throttled providers, or no
candidates). These diagnostics are logged to improve observability and
make debugging metadata fetch failures significantly easier.

packages/types/src/book.ts

@@ -1,4 +1,4 @@
-import type { MetadataProviderKey } from "./metadata-fetch";
+import type { MetadataFetchDiagnostics, MetadataProviderKey } from "./metadata-fetch";
 import type { BookMetadataLockField } from "./metadata-lock";
 import type { AudiobookChapter, NarratorRef } from "./audiobook";
 import type { ComicMetadataFields } from "./metadata-fetch";
@@ -138,6 +138,43 @@ export type BookMetadataSaveResult = {
   libraryAutoWriteEnabled: boolean;
 };
 
+export type BookMetadataRefreshPreviewFields = {
+  title?: string | null;
+  subtitle?: string | null;
+  description?: string | null;
+  authors?: string[];
+  genres?: string[];
+  publisher?: string | null;
+  publishedYear?: number | null;
+  language?: string | null;
+  pageCount?: number | null;
+  seriesName?: string | null;
+  seriesIndex?: number | null;
+  coverUrl?: string;
+  googleBooksId?: string | null;
+  goodreadsId?: string | null;
+  amazonId?: string | null;
+  hardcoverId?: string | null;
+  openLibraryId?: string | null;
+  itunesId?: string | null;
+  audibleId?: string | null;
+  koboId?: string | null;
+  comicvineId?: string | null;
+  ranobedbId?: string | null;
+  audioMetadata?: {
+    narrators?: string[];
+    durationSeconds?: number | null;
+    abridged?: boolean | null;
+    chapters?: AudiobookChapter[];
+  };
+  comicMetadata?: ComicMetadataFields;
+};
+
+export type BookMetadataRefreshPreviewResponse = {
+  metadata: BookMetadataRefreshPreviewFields;
+  diagnostics: MetadataFetchDiagnostics;
+};
+
 export type BookKoboReadingState = {
   status: string | null;
   progressPercent: number | null;

packages/types/src/metadata-fetch.ts

@@ -62,6 +62,20 @@ export interface MetadataProviderInfo {
   identifiable: boolean;
 }
 
+export type MetadataFetchEmptyReason = "no_active_providers" | "providers_throttled" | "no_candidates" | "no_resolved_fields";
+
+export interface MetadataFetchDiagnostics {
+  reason: MetadataFetchEmptyReason | null;
+  activeProviders: MetadataProviderKey[];
+  fieldRuleProviders: MetadataProviderKey[];
+  disabledFieldRuleProviders: MetadataProviderKey[];
+  enabledUnreferencedProviders: MetadataProviderKey[];
+  throttledProviders: MetadataProviderKey[];
+  candidateProviders: MetadataProviderKey[];
+  candidateCount: number;
+  resolvedFieldCount: number;
+}
+
 export interface ProviderThrottleRuntimeState {
   key: MetadataProviderKey;
   throttled: boolean;