// ── Shared scalars ──────────────────────────────────────────────────────────
type ElementCategory =
  | 'rare_earth_light'
  | 'rare_earth_heavy'
  | 'strategic_metal'
  | 'semiconductor_metal';

type ExportControlStatus = 'restricted' | 'monitored' | 'normal';
type RegulatoryStatus    = 'active' | 'suspended' | 'none';
type MarketTier          = 'retail' | 'bulk' | 'lab';
type Confidence          = 'low' | 'medium' | 'high';
type Direction           = 'up' | 'down' | 'flat';
type WindowKey           = '7d' | '30d' | '90d' | '1y' | 'all_time';
type ISODate             = string; // 'YYYY-MM-DD'
type ISODateTime         = string; // RFC3339, e.g. '2026-03-26T00:00:00Z'

// ── Element  (from _data/element_catalog.yml) ────────────────────────────────
interface Element {
  symbol: string;                       // 'Dy' — case-sensitive; used in the URL
  name: string;                         // 'Dysprosium'
  atomic_number: number;                // 66
  category: ElementCategory;            // 'rare_earth_heavy'
  family: string;                       // 'Lanthanide', 'Transition metal', 'Metalloid', ...
  default_forms: string[];              // ['oxide','metal'] | ['metal','compound'] ...
  export_control_status: ExportControlStatus;
  regulatory_status: RegulatoryStatus;
  dominant_source_country: string;      // ISO-2, e.g. 'CN'
  origin_countries: string[];           // ['CN','US','AU']
  trade_form: string;                   // 'Oxide (Dy₂O₃)'
  notes: string;
  price_tier: number;                   // 1–4
  high_demand: boolean;
  cn_export_control: boolean;
  purity_range?: string;                // optional — '99.9%–99.99%' (present on some entries)
}

// ── PriceRecord  (from _data/price_records.json — 238 records) ───────────────
interface PriceRecord {
  id: string;                           // 'R-0001'
  element_symbol: string;               // 'La'  (FK → Element.symbol)
  element_name: string;                 // 'Lanthanum'
  invoice_ref: string | null;
  original_price_per_unit: number;
  original_currency: string;            // 'USD'
  original_unit: string;                // 'kg'
  normalized_usd_per_kg: number;
  exchange_rate_used: number;           // 1.0
  exchange_rate_date: ISODate;
  form: string;                         // 'oxide' | 'metal' | 'compound' | ...
  purity: string;                       // '99.9% (3N)'
  market_tier: MarketTier;
  moq_kg: number | null;
  quoted_quantity_kg: number | null;
  incoterm: string | null;              // 'DDP' | 'FOB' | ...
  taxes_included: boolean;
  shipping_included: boolean;
  source_type: string;                  // 'distributor_offer' | 'public_listing' | 'benchmark' | ...
  source_id: string;                    // FK → Source.id, OR free-text seller for non-registry sources
  source_url: string | null;
  seller_name: string;
  seller_country: string;               // ISO-2
  verification_status: string;          // 'single_source_offer' | 'corroborated' | 'verified_invoice' | ...
  confidence_score: number;             // 0..1
  notes: string | null;
  quote_date: ISODate;                  // newest drives the footer freshness badge
  ingestion_timestamp: ISODateTime;
}

// ── PriceHistory  (from _data/price_history/<Symbol>.yml — 285 observations) ──
interface PriceObservation {
  date: ISODate;
  tier: MarketTier;
  price_per_kg: number;
  currency: string;                     // 'USD'
  source: string;                       // Source.id | free-text seller | 'median_aggregate'
  source_type: string;                  // 'public_listing' | 'aggregate' | 'benchmark' | ...
  record_id?: string;                   // 'R-0036' — absent on aggregate rows
  form?: string;                        // 'oxide' | 'metal' | 'metal, oxide'
  purity?: string;
  seller?: string;                      // present on registry-source rows
  notes?: string;                       // present on median_aggregate rows
}
interface PriceHistory {
  symbol: string;
  observations: PriceObservation[];
}

// ── Fluctuation  (from _data/fluctuations.json — keyed by symbol) ────────────
interface LatestPrice {
  contributing_observations: number;
  currency: string;
  date: ISODate;
  form_summary: string;                 // 'metal' | 'metal, oxide'
  notes: string;
  price_per_kg: number;
  source_type: string;                  // e.g. 'median_aggregate'
  sources: string[];
}
interface FluctuationWindow {
  abs_change: number;
  actual_span_days: number;
  confidence: Confidence;
  confidence_note: string;
  direction: Direction;
  distinct_days_in_window: number;      // < 3 ⇒ render rule: no line / no %move (AUDIT §3)
  end_date: ISODate;
  end_price: number;
  observations_in_window: number;
  pct_change: number;
  start_date: ISODate;
  start_price: number;
  window_days: number | null;           // null for 'all_time'
}
interface TierFluctuation {
  distinct_days: number;
  observation_count: number;
  windows: Record<WindowKey, FluctuationWindow | null>;  // null when the window has no data
}
interface Fluctuation {                  // one per element (the per-symbol value in `elements`)
  data_quality: 'sparse' | 'moderate' | 'rich';   // the three values present in the data; mostly low given the 2-day corpus
  data_since: ISODate;
  data_until: ISODate;
  distinct_days: number;
  latest_bulk_price: LatestPrice | null;
  latest_lab_price: LatestPrice | null;
  latest_retail_price: LatestPrice | null;
  observation_count: number;
  tiers: Record<MarketTier, TierFluctuation>;       // keys: 'retail' | 'bulk' | 'lab'
}
interface FluctuationsFile {
  elements: Record<string, Fluctuation>;            // keyed by element symbol
}

// ── RegulatoryNotice  (from _data/regulatory/*.yml — 5 notices) ──────────────
// The shape is the union across the 5 notices; optional fields appear only where relevant.
interface ComplianceRequirement {
  required?: boolean;                   // on end_user_certificate
  duration_working_days?: number;       // on review_period (always 45 in current data)
  legal_basis: string;
  description: string;
}
interface NoticeSuspension {            // present on suspended notices (e.g. Nos. 55–62)
  suspended_by: string;
  suspension_ref: string;
  suspension_effective: ISODate;
  suspension_expires: ISODate;          // e.g. '2026-11-28'
  notes: string;
}
interface IndividualAnnouncement {      // heterogeneous: number is int (55) or string ('1/2026')
  number: number | string;
  scope: string;
  date_effective?: ISODate;             // present on Nos. 1/17 2026
  status?: string;                      // 'active' | 'suspended'
}
interface NoticeArticle {               // present on gac_46_2024 (Art. 1 / Art. 2)
  article: number;
  scope: string;
  status: string;
  description: string;
  suspended: boolean;
  suspension_notice?: string;
  suspension_expires?: ISODate;
}
interface SanctionedEntities {          // present on mofcom_1_17_2026
  count: number;
  designation: string;
  effect: string;
  note: string;
}
interface RegulatoryNotice {
  notice_id: string;                    // 'MOFCOM/GAC No. 18/2025'
  chinese_ref: string;                  // '商务部 海关总署公告2025年第18号'
  issuing_authority: string;            // 'MOFCOM/GAC' | 'MOFCOM'
  date_issued: ISODate;
  date_effective: ISODate;
  status: 'active' | 'suspended';
  affected_elements: string[];          // element symbols
  controlled_forms: string[];           // ['metal','alloy','oxide','compound', ...]
  measure_type: string;                 // 'export_licence_required' | 'presumptive_denial' | ...
  description: string;
  compliance_requirements: {
    end_user_certificate?: ComplianceRequirement;
    review_period?: ComplianceRequirement;
  };
  notes: string[];
  // optional / variant fields (present only on some notices):
  suspension?: NoticeSuspension;
  newly_controlled_elements?: string[]; // Nos. 55–62: [Ho, Er, Tm, Eu, Yb]
  individual_announcements?: IndividualAnnouncement[];
  articles?: NoticeArticle[];           // gac_46_2024
  related_notices?: string[];           // gac_46_2024
  target_country?: string;              // mofcom_1_17_2026: 'JP'
  sanctioned_entities?: SanctionedEntities; // mofcom_1_17_2026
}

// ── PolicyEvent  (from _data/policy_events.yml — 11 events) ──────────────────
type PolicyEventType =
  | 'export_control' | 'export_ban' | 'sanction' | 'suspension' | 'regulation';
interface PolicyEvent {
  id: string;                           // 'pe-2025-04-04'
  date: ISODate;
  title: string;
  description: string;
  affected_elements: string[];          // may be [] (e.g. EU CRMA, sanctions)
  affected_forms: string[];             // may be []
  event_type: PolicyEventType;
  source_country: string;               // 'CN' | 'EU'
  source_name: string;                  // 'MOFCOM/GAC Announcement No. 18 of 2025'
  source_url: string | null;
  notes: string;                        // includes the Chinese reference string
}

// ── Source  (from _data/source_registry.yml — 5 sources) ─────────────────────
type SourceType = 'distributor' | 'marketplace';
interface Source {
  id: string;                           // 'stanford-advanced-materials-01'
  name: string;                         // 'Stanford Advanced Materials'
  type: SourceType;
  trust_tier: number;                   // 1 (highest) .. 5
  country: string;                      // ISO-2
  supported_elements: string[];         // element symbols this source quotes
  parse_status: string;                 // 'active'
  review_status: string;                // 'reviewed'
}