/**
 * Loading Config Schema Definitions
 *
 * Configuration for model loading behavior: shard caching, memory management,
 * and storage settings. These values were previously hardcoded across the codebase.
 *
 * @module config/schema/loading
 */

import type { DistributionConfigSchema } from './distribution.schema.js';
import type { StorageFullConfigSchema } from './storage.schema.js';

/**
 * Default Q4K layout when manifest doesn't specify one (backwards compatibility).
 * 'row' = row-wise layout, compatible with fused Q4K kernels
 * 'col' = column-wise layout, requires dequantization
 */
export declare const DEFAULT_Q4K_LAYOUT: 'row';

/**
 * Configuration for the shard LRU cache.
 *
 * The cache stores recently-used model shards to avoid redundant disk/network reads.
 * Different loading scenarios need different cache sizes:
 * - OPFS (disk): Small cache (2 shards) since disk reads are fast
 * - Network: Large cache (16 shards) to avoid re-fetching over network
 * - MoE: Dynamic sizing based on experts per token
 */
export interface ShardCacheConfigSchema {
  /** Max entries when loading from OPFS (disk reads are fast) */
  opfsEntries: number;

  /** Max entries when loading from network (avoid re-fetching) */
  networkEntries: number;

  /** Max entries for MoE models (caps the dynamic formula) */
  moeMaxEntries: number;

  /** Verify shard hashes when loading into cache */
  verifyHashes: boolean;

  /** Max concurrent shard loads (0 = unlimited) */
  maxConcurrentLoads: number;

  /** Coalesced range-fetch block size in bytes (0 = disabled) */
  rangeCacheBlockBytes: number;

  /** Maximum resident bytes for coalesced range-fetch blocks (0 = disabled) */
  rangeCacheMaxBytes: number;

  /** Minimum requested range size that may use coalesced range-fetch blocks */
  rangeCacheMinBytes: number;
}

/** Default shard cache configuration */
export declare const DEFAULT_SHARD_CACHE_CONFIG: ShardCacheConfigSchema;

/**
 * Configuration for memory management during model loading.
 *
 * Controls when to flush caches and GPU queues to manage memory pressure.
 */
export interface LoaderMemoryBudgetConfigSchema {
  /** Enable resident-memory fail-closed protection during loading */
  enabled: boolean;

  /** Absolute resident-memory cap in bytes (null = derive from system memory) */
  maxResidentBytes: number | null;

  /** Fraction of system memory to allow when deriving maxResidentBytes (null = disabled) */
  systemMemoryFraction: number | null;

  /** Bytes to reserve for the OS and sibling processes when deriving maxResidentBytes */
  reserveBytes: number;

  /** Minimum derived resident-memory budget in bytes */
  minimumBudgetBytes: number;
}

/** Default loader memory budget configuration */
export declare const DEFAULT_LOADER_MEMORY_BUDGET_CONFIG: LoaderMemoryBudgetConfigSchema;

/**
 * Configuration for memory management during model loading.
 *
 * Controls when to flush caches and GPU queues to manage memory pressure.
 */
export interface MemoryManagementConfigSchema {
  /** Flush shard cache every N layers during loading */
  flushIntervalLayers: number;

  /** Flush shard cache when it exceeds this size in bytes */
  flushThresholdBytes: number;

  /** Flush GPU queue every N layers (releases Chrome staging memory) */
  gpuQueueFlushLayers: number;

  /** Log memory stats every N milliseconds during loading */
  logIntervalMs: number;

  /** Resident-memory admission and fail-closed budget */
  budget: LoaderMemoryBudgetConfigSchema;
}

/** Default memory management configuration */
export declare const DEFAULT_MEMORY_MANAGEMENT_CONFIG: MemoryManagementConfigSchema;

/**
 * Configuration for speculative shard prefetching across layers.
 */
export interface PrefetchConfigSchema {
  /** Enable prefetching of upcoming layer shards */
  enabled: boolean;

  /** Number of layers ahead to prefetch */
  layersAhead: number;

  /** Max shards to prefetch per layer step (0 = no limit) */
  maxShards: number;

  /** Allow whole-shard prefetch when a custom range loader is present */
  allowRangeLoaderPrefetch: boolean;
}

/** Default prefetch configuration */
export declare const DEFAULT_PREFETCH_CONFIG: PrefetchConfigSchema;

/**
 * Configuration for OPFS directory paths.
 *
 * Note: This is distinct from StorageFullConfigSchema (in storage.schema.js)
 * which handles quota, VRAM estimation, and alignment settings.
 */
export interface OpfsPathConfigSchema {
  /** Root directory name in OPFS for model storage */
  opfsRootDir: string;
}

/** Default OPFS path configuration */
export declare const DEFAULT_OPFS_PATH_CONFIG: OpfsPathConfigSchema;

/**
 * Configuration for the MoE expert LRU cache.
 *
 * Controls how much VRAM is allocated for caching expert weights.
 */
export interface ExpertCacheConfigSchema {
  /** Default maximum cache size in bytes */
  defaultSizeBytes: number;

  /** Maximum percentage of adapter's maxBufferSize to use (0-1) */
  maxBufferPercentage: number;

  /** Fallback maxBufferSize when adapter limits are unavailable */
  maxBufferFallbackBytes: number;

  /** Watermark ratio (0-1) that triggers eager eviction before hard limit */
  evictionHighWatermark: number;

  /** Target ratio (0-1) after emergency trim when over max size */
  emergencyTrimToRatio: number;

  /** GPT-OSS packed expert pager controls */
  gptOssPager: {
    enabled: boolean;
    maxResidentLayers: number;
  };
}

/** Default expert cache configuration */
export declare const DEFAULT_EXPERT_CACHE_CONFIG: ExpertCacheConfigSchema;

/**
 * Complete loading configuration schema.
 *
 * Controls all aspects of model loading behavior.
 */
export interface LoadingConfigSchema {
  /** OPFS quota, VRAM estimation, alignment */
  storage: StorageFullConfigSchema;
  /** Network/download settings */
  distribution: DistributionConfigSchema;
  shardCache: ShardCacheConfigSchema;
  memoryManagement: MemoryManagementConfigSchema;
  prefetch: PrefetchConfigSchema;
  opfsPath: OpfsPathConfigSchema;
  expertCache: ExpertCacheConfigSchema;
  /** Allow F16->F32 upcast for non-matmul weights (norms, softcap) */
  allowF32UpcastNonMatmul: boolean;
}

/** Default loading configuration */
export declare const DEFAULT_LOADING_CONFIG: LoadingConfigSchema;