Improve documentation and error messages for build options support

resource/src/main/java/com/hellblazer/luciferase/resource/compute/ComputeKernel.java

@@ -54,9 +54,14 @@ public interface ComputeKernel extends AutoCloseable {
      *   <li>Architecture-specific tuning: {@code "-D__GCN_REV__=2"}</li>
      * </ul>
      *
+     * <p><b>Security Note:</b> Build options are passed directly to the backend compiler without
+     * sanitization. Ensure options originate from trusted sources only to prevent compiler-based
+     * denial-of-service or unexpected behavior.
+     *
      * @param source       Kernel source code (Metal or OpenCL)
      * @param entryPoint   Kernel entry point function name
-     * @param buildOptions Compiler flags and preprocessor defines (null or empty for defaults)
+     * @param buildOptions Compiler flags and preprocessor defines (null or empty for defaults).
+     *                     Passed directly to the backend compiler without validation.
      * @throws KernelCompilationException if compilation fails
      * @see #recompile(String, String, String)
      */
@@ -69,8 +74,7 @@ default void compile(String source, String entryPoint, String buildOptions)
      * Recompile an already-compiled kernel with different build options.
      *
      * <p>Enables runtime GPU auto-tuning by recompiling kernels with different optimization
-     * parameters without clearing existing kernel state. Useful for performance experiments
-     * and adaptive optimization strategies.
+     * parameters. Useful for performance experiments and adaptive optimization strategies.
      *
      * <h3>Recompilation Workflow:</h3>
      * <pre>{@code
@@ -83,8 +87,13 @@ default void compile(String source, String entryPoint, String buildOptions)
      * kernel.execute(globalSize);  // Compare performance
      * }</pre>
      *
-     * <p><b>Note:</b> Recompilation creates a fresh kernel. The old kernel reference remains
-     * valid until explicitly closed, allowing multiple kernel variants to coexist.
+     * <p><b>Note:</b> Recompilation releases the old kernel and program resources, then compiles
+     * a fresh kernel. The kernel object itself remains valid and usable after recompilation.
+     *
+     * <p><b>Thread Safety:</b> During recompilation, {@link #isCompiled()} may briefly return false
+     * as resources are released and replaced. Concurrent kernel execution from other threads during
+     * recompilation will fail with IllegalStateException. Callers must ensure exclusive access to
+     * the kernel object during recompilation.
      *
      * @param source       Kernel source code (must match original source for consistency)
      * @param entryPoint   Kernel entry point function name

resource/src/main/java/com/hellblazer/luciferase/resource/compute/opencl/OpenCLKernel.java

@@ -89,7 +89,8 @@ public void compile(String source, String entryPoint) throws KernelCompilationEx
     public void compile(String source, String entryPoint, String buildOptions) throws KernelCompilationException {
         checkNotClosed();
         if (compiled.get()) {
-            throw new KernelCompilationException("Kernel already compiled");
+            throw new KernelCompilationException(
+                    "Kernel already compiled. Use recompile() to recompile with different build options.");
         }
 
         compileInternal(source, entryPoint, buildOptions);
@@ -150,12 +151,8 @@ private void compileInternal(String source, String entryPoint, String buildOptio
             checkCLError(errcode.get(0), "Failed to create OpenCL kernel: " + entryPoint);
 
             compiled.set(true);
-            if (buildOptions != null && !buildOptions.isEmpty()) {
-                log.debug("Compiled OpenCL kernel: {} (entry point: {}, options: {})",
-                        name, entryPoint, buildOptions);
-            } else {
-                log.debug("Compiled OpenCL kernel: {} (entry point: {})", name, entryPoint);
-            }
+            log.debug("Compiled OpenCL kernel: {} (entry point: {}, options: {})",
+                    name, entryPoint, buildOptions != null ? buildOptions : "(none)");
 
         } catch (Exception e) {
             cleanup();

resource/src/test/java/com/hellblazer/luciferase/resource/compute/ComputeKernelBuildOptionsTest.java

@@ -101,6 +101,10 @@ static void checkOpenCL() {
 
     // --- Basic Build Options Tests ---
 
+    /**
+     * Validates that preprocessor defines work with kernel compilation.
+     * Tests basic -D option passing to the OpenCL compiler.
+     */
     @Test
     void testCompileWithDefine() {
         if (!openCLAvailable) return;
@@ -152,6 +156,10 @@ void testCompileWithoutFeatureFlag() {
 
     // --- Compiler Flags Tests ---
 
+    /**
+     * Validates that OpenCL compiler flags (e.g., -cl-fast-relaxed-math) work correctly.
+     * These flags enable performance optimizations and are critical for GPU auto-tuning.
+     */
     @Test
     void testCompileWithCompilerFlags() {
         if (!openCLAvailable) return;
@@ -196,6 +204,11 @@ void testRecompileWithDifferentOptions() {
         }
     }
 
+    /**
+     * Validates that recompilation changes the runtime behavior of the kernel.
+     * First execution multiplies by 2, second by 5, demonstrating that the
+     * new build options take effect. Critical for GPU auto-tuning workflows.
+     */
     @Test
     void testRecompileChangesDefineValue() throws Exception {
         if (!openCLAvailable) return;