KernelOPT 2026: Arsitektur Dispatch-Aware Agentic Search, 5 Profiling-Guided LLM Agents, dan 4-Gate Verification Cascade untuk Optimasi GPU Triton Kernel & PyTorch Inductor

// KernelOPT: Dispatch-Aware GPU Kernel Search & Verification Engine
// Berdasarkan Prinsip Arsitektur Riset arXiv:2609.30059 (Red Hat PyTorch Team, September 2026)
//
// Pilar Sistem:
// 1. Dispatch-Aware IR Parser: Memisahkan cuBLAS/cuDNN extern calls vs generated Triton blocks
// 2. NCU Bottleneck Tier Classifier: Membagi kondisi hardware ke 4 kuadran (SOLcomp vs SOLmem)
// 3. Meltdown Detector: Mencegah keruntuhan diversitas search plan pada LangGraph loop
// 4. Profiling-Guided Beam Search: Eksplorasi-eksploitasi pohon transformasi dengan UCB (c=1.4)
// 5. 4-Gate Verification Cascade: Static -> Multi-Seed Correctness -> Float64 Fallback (ρ) -> Performance Gate

export type BottleneckTier = 'NEAR_OPTIMAL' | 'MEMORY_BOUND' | 'COMPUTE_BOUND' | 'UNDERUTILIZED';

export interface NCUMetrics {
  kernelName: string;
  durationUs: number;
  solComputePct: number;    // Speed-of-Light Compute %
  solMemoryPct: number;     // Speed-of-Light Memory Throughput %
  registersPerThread: number;
  achievedOccupancyPct: number;
  dramThroughputGBS: number;
  topNcuRules: Array<{ ruleName: string; estimatedSpeedupPct: number; recommendation: string }>;
}

export interface InductorKernelBlock {
  id: string;
  kind: 'EXTERN_LIBRARY' | 'TRITON_GENERATED';
  targetSymbol: string;     // e.g. aten.mm -> extern_kernels.mm (cuBLAS) vs triton_poi_fused_0
  rawCode: string;
  fusibleDependencies: string[];
  needsReplacement: boolean;
}

export interface OptimizationCandidate {
  id: string;
  parentId: string | null;
  tritonCode: string;
  latencyUs: number;
  ncuMetrics: NCUMetrics;
  bottleneckTier: BottleneckTier;
  transformationDescription: string;
  visitCount: number;
}

export interface GateVerificationResult {
  passed: boolean;
  gateIndex: 1 | 2 | 3 | 4;
  gateName: 'STATIC_VALIDATION' | 'MULTI_SEED_CORRECTNESS' | 'FLOAT64_FALLBACK_MODEL_LEVEL' | 'PERFORMANCE_GATE';
  speedupRatio: number;
  errorRatioRho?: number;
  rejectionReason?: string;
}

/**
 * 1. Dispatch-Aware IR Analyzer
 * Mendeteksi panggilan vendor library (cuBLAS/cuDNN) dari output TorchInductor
 * dan memastikannya tidak ditimpa secara ceroboh oleh kernel Triton yang lebih lambat.
 */
export class DispatchAwareIRAnalyzer {
  public static parseInductorOutput(inductorPythonSrc: string): InductorKernelBlock[] {
    const blocks: InductorKernelBlock[] = [];
    const lines = inductorPythonSrc.split('\n');

    for (let i = 0; i < lines.length; i++) {
      const line = lines[i].trim();

      // Deteksi extern_kernels (cuBLAS gemm, cuDNN conv, aten.bmm)
      if (line.includes('extern_kernels.') || line.includes('torch.ops.aten.')) {
        blocks.push({
          id: `extern-${i}`,
          kind: 'EXTERN_LIBRARY',
          targetSymbol: line.split('(')[0],
          rawCode: line,
          fusibleDependencies: [],
          needsReplacement: false, // PRESERVE VENDOR CALL
        });
      } else if (line.includes('async_compile.triton(') || line.includes('@triton.jit')) {
        // Blok kernel Triton yang digenerate oleh Inductor -> Target Optimasi
        blocks.push({
          id: `triton-${i}`,
          kind: 'TRITON_GENERATED',
          targetSymbol: `triton_subkernel_${i}`,
          rawCode: line,
          fusibleDependencies: [],
          needsReplacement: true, // CANDIDATE FOR AGENTIC SEARCH
        });
      }
    }
    return blocks;
  }
}

/**
 * 2. NCU Bottleneck Tier Classifier
 * Mengklasifikasikan bottleneck hardware secara deterministik berdasarkan metrik NCU Speed-of-Light.
 */
export class NCUBottleneckClassifier {
  public static classify(metrics: NCUMetrics): BottleneckTier {
    const { solComputePct, solMemoryPct } = metrics;

    if (solComputePct > 80 || solMemoryPct > 80) {
      return 'NEAR_OPTIMAL';
    }
    if (solMemoryPct > solComputePct && solMemoryPct <= 80) {
      return 'MEMORY_BOUND';
    }
    if (solComputePct > solMemoryPct && solComputePct <= 80) {
      return 'COMPUTE_BOUND';
    }
    return 'UNDERUTILIZED';
  }
}

/**
 * 3. Meltdown Detector
 * Mencegah degradasi variasi ide di mana planner terus-menerus mengusulkan transformasi yang identik
 * (misal hanya mengubah num_stages atau block_size tanpa inovasi memori/aljabar).
 */
export class PlanMeltdownDetector {
  public static isMeltdownDetected(recentApproaches: string[], thresholdUnique: number = 2): boolean {
    if (recentApproaches.length < 5) return false;
    const window = recentApproaches.slice(-6);
    const normalized = new Set(
      window.map((s) => s.toLowerCase().replace(/[^a-z0-9]/g, ''))
    );
    return normalized.size <= thresholdUnique;
  }
}

/**
 * 4. Profiling-Guided Beam Search dengan Upper Confidence Bound (UCB)
 * Menyeimbangkan eksploitasi jalur latensi terendah dengan eksplorasi cabang kernel yang belum terjamah.
 */
export class ProfilingGuidedBeamSearch {
  private cExploration: number = 1.4;

  public computeUCBScore(
    candidate: OptimizationCandidate,
    baselineLatencyUs: number,
    totalTreeVisits: number
  ): number {
    const exploitation = baselineLatencyUs / Math.max(1e-6, candidate.latencyUs);
    const exploration = this.cExploration * Math.sqrt(
      Math.log(Math.max(1, totalTreeVisits)) / Math.max(1, candidate.visitCount)
    );
    return exploitation + exploration;
  }

  public selectNextBeam(
    candidates: OptimizationCandidate[],
    baselineLatencyUs: number,
    beamWidth: number = 4
  ): OptimizationCandidate[] {
    const totalVisits = candidates.reduce((sum, c) => sum + c.visitCount, 0);
    return [...candidates]
      .sort((a, b) => {
        const scoreA = this.computeUCBScore(a, baselineLatencyUs, totalVisits);
        const scoreB = this.computeUCBScore(b, baselineLatencyUs, totalVisits);
        return scoreB - scoreA;
      })
      .slice(0, beamWidth);
  }
}

/**
 * 5. The Four-Gate Verification Cascade
 * Filter 4 tahap ketat yang menjamin model hasil restitch 100% identik secara numerik
 * dan bebas dari regresi performa.
 */
export class FourGateVerificationCascade {
  /**
   * Gate 1: Static Validation (Syntax, Triton compile check, register bounds)
   */
  public verifyGate1(tritonCode: string): { ok: boolean; reason?: string } {
    if (!tritonCode.includes('@triton.jit')) {
      return { ok: false, reason: 'Missing @triton.jit decorator' };
    }
    if (tritonCode.includes('tl.load') && !tritonCode.includes('mask=')) {
      return { ok: false, reason: 'Out-of-bounds safety violation: tl.load missing mask parameter' };
    }
    return { ok: true };
  }

  /**
   * Gate 2: Multi-Seed Correctness pada Isolated Sub-Kernel (3 seeds, allclose rtol=1e-3, atol=1e-3)
   */
  public verifyGate2(maxAbsDiffAcrossSeeds: number[]): { ok: boolean; reason?: string } {
    const tolerance = 1e-3;
    const fails = maxAbsDiffAcrossSeeds.filter((d) => d > tolerance);
    if (fails.length > 0) {
      return {
        ok: false,
        reason: `Multi-seed discrepancy: ${fails.length}/3 seeds exceeded ${tolerance} absolute error.`,
      };
    }
    return { ok: true };
  }

  /**
   * Gate 3: Model-Level Float64 Fallback Verification (ρ-ratio arbitration)
   * Menyambung kembali sub-kernel ke dalam model PyTorch nn.Module utuh.
   * Menghitung rasio kesalahan presisi:
   * ρ = ||y_opt - y_ref_fp32||_inf / (||y_ref_fp64 - y_ref_fp32||_inf + ε)
   */
  public verifyGate3(
    diffOptFp32: number,
    diffRefFp64Fp32: number,
    epsilon: number = 1e-6
  ): { ok: boolean; rho: number; reason?: string } {
    const rho = diffOptFp32 / (diffRefFp64Fp32 + epsilon);
    // Jika rho <= 1.5, perbedaan numerik terbukti hanyalah variasi akumulasi fp32 yang valid
    if (rho > 1.5 && diffOptFp32 > 1e-3) {
      return {
        ok: false,
        rho,
        reason: `Model-level precision violation: error ratio ρ=${rho.toFixed(2)} exceeds 1.5x reference floating-point variance.`,
      };
    }
    return { ok: true, rho };
  }

  /**
   * Gate 4: Performance Gate (End-to-End Speedup Verification)
   * Wajib melampaui torch.compile baseline (>1.01x) pada model utuh.
   * Mencegah local speedup yang justru memperlambat keseluruhan pipeline akibat dispatch overhead.
   */
  public verifyGate4(
    baselineE2ELatencyMs: number,
    restitchedE2ELatencyMs: number
  ): { ok: boolean; speedup: number; reason?: string } {
    const speedup = baselineE2ELatencyMs / restitchedE2ELatencyMs;
    if (speedup < 1.01) {
      return {
        ok: false,
        speedup,
        reason: `Performance gate rejected: measured speedup (${speedup.toFixed(3)}x) <= 1.01x compiler baseline threshold.`,
      };
    }
    return { ok: true, speedup };
  }
}

/**
 * 6. Asymmetric Experience Memory
 * FIFO Queue dengan seleksi asimetris:
 * Simpan pengalaman jika speedup >= 1.05x (perbaikan nyata) ATAU jika regresi >= 1.20x (kegagalan fatal).
 * Pengetahuan tentang regresi jauh lebih krusial untuk mencegah planner terjebak pada antipattern.
 */
export interface ExperienceEntry {
  strategyName: string;
  bottleneck: BottleneckTier;
  speedup: number;
  ncuGuidelineLearned: string;
  status: 'ACCEPTED' | 'REJECTED' | 'AVOID';
}

export class AsymmetricExperienceMemory {
  private queue: ExperienceEntry[] = [];
  private capacity: number = 100;
  private strategyStats: Map = new Map();

  public record(entry: ExperienceEntry): boolean {
    const sPlus = 1.05;
    const sMinus = 1.20; // 1 / 1.20 = 0.833 (regresi >16.7%)

    const isSpeedupSignificant = entry.speedup >= sPlus;
    const isRegressionSignificant = (1.0 / entry.speedup) >= sMinus;

    // Asymmetric Filtering Rule (Equation 6)
    if (!isSpeedupSignificant && !isRegressionSignificant) {
      return false; // Abaikan perbaikan marginal atau noise kecil
    }

    // Update cross-run strategy success tracking
    const stats = this.strategyStats.get(entry.strategyName) || { attempts: 0, successes: 0 };
    stats.attempts++;
    if (entry.speedup >= 1.01) stats.successes++;
    this.strategyStats.set(entry.strategyName, stats);

    if (stats.attempts >= 3 && (stats.successes / stats.attempts) < 0.3) {
      entry.status = 'AVOID';
    }

    if (this.queue.length >= this.capacity) {
      this.queue.shift();
    }
    this.queue.push(entry);
    return true;
  }

  public getGuidelines(): string[] {
    return this.queue
      .filter((e) => e.status === 'ACCEPTED' || e.status === 'AVOID')
      .map((e) => `[${e.status}] Strategy "${e.strategyName}" for ${e.bottleneck}: ${e.ncuGuidelineLearned}`);
  }
}