/**
 * Platform Config Schema Definitions
 *
 * Defines the structure for device-family platform configurations.
 * Platforms provide detection metadata and memory hints for GPU families.
 *
 * Note: GPU capabilities (hasSubgroups, hasF16, etc.) are detected at runtime,
 * not stored in config. Platforms assume those capabilities are available.
 *
 * @module config/schema/platform
 */

/**
 * Patterns for detecting which platform to use based on GPU adapter info.
 */
export type PlatformDetectionPattern = string | string[];

export interface PlatformDetectionSchema {
  /** Vendor string pattern or patterns (e.g., "apple", "nvidia", "amd") */
  vendor?: PlatformDetectionPattern;

  /** Architecture pattern or patterns (e.g., "gpu-family-apple-9") */
  architecture?: PlatformDetectionPattern;

  /** Device name pattern or patterns (e.g., "M3", "RTX 4090") */
  device?: PlatformDetectionPattern;

  /** WebGPU adapter description pattern or patterns */
  description?: PlatformDetectionPattern;
}

/**
 * Memory-related hints for this platform.
 */
export interface MemoryHintsSchema {
  /** Whether to prefer unified memory strategies (Apple Silicon) */
  preferUnifiedMemory?: boolean;

  /** Optimal buffer alignment in bytes */
  bufferAlignment?: number;

  /** Optimal shard size for this platform */
  optimalShardSize?: number;

  /** Maximum recommended buffer pool size */
  maxBufferPoolSize?: number;
}

/**
 * Complete platform configuration for a GPU device family.
 */
export interface PlatformSchema {
  /** Unique identifier (e.g., "apple-m3", "nvidia-rtx40") */
  id: string;

  /** Human-readable name */
  name: string;

  /** Detection patterns to match this platform */
  detection: PlatformDetectionSchema;

  /** Memory hints */
  memoryHints?: MemoryHintsSchema;

  /** Whether this is a fallback/generic platform */
  isGeneric?: boolean;

  /** Notes about this platform */
  notes?: string;
}

/**
 * GPU capabilities detected at runtime.
 * These are NOT stored in config files - they come from WebGPU adapter.
 */
export interface RuntimeCapabilities {
  /** Whether shader-f16 feature is available */
  hasF16: boolean;

  /** Whether subgroups feature is available */
  hasSubgroups: boolean;

  /** Subgroup size (if subgroups available) */
  subgroupSize?: number;

  /** Maximum workgroup size per dimension */
  maxWorkgroupSize: number;

  /** Maximum compute workgroup storage (shared memory) in bytes */
  maxSharedMemory: number;

  /** Maximum storage buffer binding size */
  maxStorageBufferBindingSize: number;

  /** Maximum buffer size */
  maxBufferSize: number;
}

/**
 * Platform config with runtime capabilities merged in.
 * This is what GPU kernel selection consumes.
 */
export interface ResolvedPlatformConfig {
  /** Platform configuration */
  platform: PlatformSchema;

  /** Runtime-detected GPU capabilities */
  capabilities: RuntimeCapabilities;
}

/**
 * Collection of all available platform configs.
 */
export interface PlatformRegistrySchema {
  /** Schema version */
  version: string;

  /** All platform configs by ID */
  platforms: Record<string, PlatformSchema>;

  /** ID of the generic/fallback platform */
  fallbackId: string;
}