/**
 * Internal candidate search result model returned by search provider extractors.
 * Passed to CanonicalSearchResultBuilder to produce a public canonical SearchResult.
 * Not exposed outside the search engine core.
 */
export interface InternalProviderResult {
  /** Candidate title string extracted from provider response */
  title?: string;

  /** Candidate URL string extracted from provider response */
  url?: string;

  /** Candidate snippet text extracted from provider response */
  snippetCandidate?: string;

  /** Candidate published date string */
  publishedDate?: string;

  /** Candidate author string */
  author?: string;

  /** Candidate relevance score */
  score?: number;

  /** Provider identity name (e.g. "exa", "duckduckgo") */
  source: string;

  /** Internal raw provider item (for diagnostics / logging only; omitted from canonical SearchResult) */
  raw?: Record<string, unknown>;

  /** Optional diagnostic metadata for logging and development debugging */
  debug?: {
    snippetSource?: string;
    [key: string]: unknown;
  };
}

/**
 * Internal candidate search result model returned by search provider extractors.
 * Passed to CanonicalSearchResultBuilder to produce a public canonical SearchResult.
 * Not exposed outside the search engine core.
 */
export interface InternalProviderResult {
  /** Candidate title string extracted from provider response */
  title?: string;

  /** Candidate URL string extracted from provider response */
  url?: string;

  /** Candidate snippet text extracted from provider response */
  snippetCandidate?: string;

  /** Candidate published date string */
  publishedDate?: string;

  /** Candidate author string */
  author?: string;

  /** Candidate relevance score */
  score?: number;

  /** Provider identity name (e.g. "exa", "duckduckgo") */
  source: string;

  /** Internal raw provider item (for diagnostics / logging only; omitted from canonical SearchResult) */
  raw?: Record<string, unknown>;

  /** Optional diagnostic metadata for logging and development debugging */
  debug?: {
    snippetSource?: string;
    [key: string]: unknown;
  };
}