Add minimize API

examples/junit/src/test/java/com/example/BUILD.bazel

@@ -393,3 +393,24 @@ java_fuzz_target_test(
         "@maven//:org_junit_jupiter_junit_jupiter_api",
     ],
 )
+
+# Test for the minimize() hill-climbing API.
+# This test uses Jazzer.minimize() to guide the fuzzer toward minimizing
+# a "temperature" value, demonstrating inverse hill-climbing behavior.
+java_fuzz_target_test(
+    name = "CoolerFuzzTest",
+    srcs = ["CoolerFuzzTest.java"],
+    allowed_findings = ["java.lang.RuntimeException"],
+    env = {"JAZZER_FUZZ": "1"},
+    target_class = "com.example.CoolerFuzzTest",
+    verify_crash_reproducer = False,
+    runtime_deps = [
+        ":junit_runtime",
+    ],
+    deps = [
+        "//src/main/java/com/code_intelligence/jazzer/api:hooks",
+        "//src/main/java/com/code_intelligence/jazzer/junit:fuzz_test",
+        "//src/main/java/com/code_intelligence/jazzer/mutation/annotation",
+        "@maven//:org_junit_jupiter_junit_jupiter_api",
+    ],
+)

examples/junit/src/test/java/com/example/CoolerFuzzTest.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2026 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example;
+
+import com.code_intelligence.jazzer.api.Jazzer;
+import com.code_intelligence.jazzer.junit.FuzzTest;
+import com.code_intelligence.jazzer.mutation.annotation.NotNull;
+
+/**
+ * Example demonstrating the minimize() hill-climbing API.
+ *
+ * <p>Mirror of ReactorFuzzTest: instead of heating up a reactor, we're trying to cool down a system
+ * to the lowest possible temperature.
+ */
+public class CoolerFuzzTest {
+
+  @FuzzTest
+  public void fuzz(@NotNull String input) {
+    for (char c : input.toCharArray()) {
+      if (c < 32 || c > 126) return;
+    }
+    controlCooler(input);
+  }
+
+  private void controlCooler(String commands) {
+    long temperature = 4000; // Starts hot
+
+    for (char cmd : commands.toCharArray()) {
+      // Complex, chaotic feedback loop.
+      // Hard to predict which character decreases temperature.
+      if ((temperature ^ cmd) % 3 == 0) {
+        temperature -= (cmd % 10); // Cool down slightly
+      } else if ((temperature ^ cmd) % 3 == 1) {
+        temperature += (cmd % 8); // Heat up slightly
+      } else {
+        temperature -= 1; // Tiny decrease
+      }
+
+      // Cap at reasonable bounds
+      if (temperature < 0) temperature = 0;
+      if (temperature > 5000) temperature = 5000;
+    }
+
+    // THE GOAL: MINIMIZATION
+    // Drive 'temperature' to the lowest possible value.
+    Jazzer.minimize(temperature, 0, 4000);
+    if (temperature <= 100) {
+      throw new RuntimeException("Supercooled! Temperature minimized.");
+    }
+  }
+}

src/main/java/com/code_intelligence/jazzer/api/Jazzer.java

@@ -380,6 +380,95 @@ public static void maximize(long value, long minValue, long maxValue, int numCou
     // Without instrumentation, this is a no-op.
   }
 
+  /**
+   * Core implementation of the hill-climbing minimize API. It maps {@code value} from the range
+   * [{@code minValue}, {@code maxValue}] onto {@code numCounters} coverage counters via inverse
+   * linear interpolation, then sets all counters from 0 to the mapped offset.
+   *
+   * <p>Lower values produce more signal (more counters set), which causes the fuzzer to prefer
+   * inputs that result in lower values. Values above {@code maxValue} produce no signal. Values
+   * below {@code minValue} are clamped.
+   *
+   * <p>Must be invoked with the same {@code minValue}, {@code maxValue}, and {@code numCounters}
+   * for a given {@code id} across all calls. Passing different values is illegal.
+   *
+   * @param value the value to minimize
+   * @param minValue the minimum expected value (inclusive)
+   * @param maxValue the maximum expected value (inclusive); must be &gt;= {@code minValue}
+   * @param numCounters the number of counters to allocate; must be &gt; 0
+   * @param id a unique identifier for this call site (must be consistent across runs)
+   * @throws JazzerApiException if {@code maxValue < minValue} or {@code numCounters <= 0}
+   */
+  public static void minimize(long value, long minValue, long maxValue, int numCounters, int id) {
+    if (COUNTERS_TRACKER_ALLOCATE == null) {
+      return;
+    }
+
+    try {
+      ensureRangeConsistent(id, minValue, maxValue);
+      int effectiveCounters = effectiveCounters(minValue, maxValue, numCounters);
+      COUNTERS_TRACKER_ALLOCATE.invokeExact(id, effectiveCounters);
+
+      if (value <= maxValue) {
+        int toOffset;
+        if (minValue == maxValue) {
+          toOffset = 0;
+        } else {
+          double range = (double) maxValue - (double) minValue;
+          double offset = (double) maxValue - (double) Math.max(value, minValue);
+          toOffset = (int) (offset / range * (effectiveCounters - 1));
+        }
+        COUNTERS_TRACKER_SET_RANGE.invokeExact(id, toOffset);
+      }
+    } catch (JazzerApiException e) {
+      throw e;
+    } catch (Throwable e) {
+      throw new JazzerApiException("minimize: " + e.getMessage(), e);
+    }
+  }
+
+  /**
+   * Convenience overload of {@link #minimize(long, long, long, int, int)} that uses {@link
+   * #DEFAULT_NUM_COUNTERS} counters and an automatically generated call-site id.
+   *
+   * <p>During instrumentation, calls to this method are replaced by a hook that supplies a unique
+   * id for each call site. Without instrumentation, this is a no-op.
+   *
+   * <pre>{@code
+   * // Minimize temperature in [0, 4000]
+   * Jazzer.minimize(temperature, 0, 4000);
+   * }</pre>
+   *
+   * @param value the value to minimize
+   * @param minValue the minimum expected value (inclusive)
+   * @param maxValue the maximum expected value (inclusive)
+   * @see #minimize(long, long, long, int, int)
+   */
+  public static void minimize(long value, long minValue, long maxValue) {
+    // Instrumentation replaces calls to this method with the core overload using
+    // DEFAULT_NUM_COUNTERS and an automatically generated call-site id.
+    // Without instrumentation, this is a no-op.
+  }
+
+  /**
+   * Convenience overload of {@link #minimize(long, long, long, int, int)} that uses a custom number
+   * of counters and an automatically generated call-site id.
+   *
+   * <p>During instrumentation, calls to this method are replaced by a hook that supplies a unique
+   * id for each call site. Without instrumentation, this is a no-op.
+   *
+   * @param value the value to minimize
+   * @param minValue the minimum expected value (inclusive)
+   * @param maxValue the maximum expected value (inclusive)
+   * @param numCounters the number of counters to allocate; must be &gt; 0
+   * @see #minimize(long, long, long, int, int)
+   */
+  public static void minimize(long value, long minValue, long maxValue, int numCounters) {
+    // Instrumentation replaces calls to this method with the core overload using
+    // the given numCounters and an automatically generated call-site id.
+    // Without instrumentation, this is a no-op.
+  }
+
   /**
    * Make Jazzer report the provided {@link Throwable} as a finding.
    *

src/main/java/com/code_intelligence/jazzer/runtime/JazzerApiHooks.java

@@ -78,4 +78,39 @@ public static void maximizeWithCustomCountersAndId(
     Jazzer.maximize(
         (long) arguments[0], (long) arguments[1], (long) arguments[2], (int) arguments[3], hookId);
   }
+
+  /**
+   * Replaces calls to {@link Jazzer#minimize(long, long, long)} with calls to {@link
+   * Jazzer#minimize(long, long, long, int, int)} using {@link Jazzer#DEFAULT_NUM_COUNTERS} and the
+   * hook id.
+   */
+  @MethodHook(
+      type = HookType.REPLACE,
+      targetClassName = "com.code_intelligence.jazzer.api.Jazzer",
+      targetMethod = "minimize",
+      targetMethodDescriptor = "(JJJ)V")
+  public static void minimizeWithDefaultCountersAndId(
+      MethodHandle method, Object thisObject, Object[] arguments, int hookId) {
+    Jazzer.minimize(
+        (long) arguments[0],
+        (long) arguments[1],
+        (long) arguments[2],
+        Jazzer.DEFAULT_NUM_COUNTERS,
+        hookId);
+  }
+
+  /**
+   * Replaces calls to {@link Jazzer#minimize(long, long, long, int)} with calls to {@link
+   * Jazzer#minimize(long, long, long, int, int)} using the hook id.
+   */
+  @MethodHook(
+      type = HookType.REPLACE,
+      targetClassName = "com.code_intelligence.jazzer.api.Jazzer",
+      targetMethod = "minimize",
+      targetMethodDescriptor = "(JJJI)V")
+  public static void minimizeWithCustomCountersAndId(
+      MethodHandle method, Object thisObject, Object[] arguments, int hookId) {
+    Jazzer.minimize(
+        (long) arguments[0], (long) arguments[1], (long) arguments[2], (int) arguments[3], hookId);
+  }
 }

src/test/java/com/code_intelligence/jazzer/api/BUILD.bazel

@@ -41,3 +41,22 @@ java_test(
         "@maven//:junit_junit",
     ],
 )
+
+java_test(
+    name = "MinimizeTest",
+    size = "small",
+    srcs = [
+        "MinimizeTest.java",
+    ],
+    target_compatible_with = SKIP_ON_WINDOWS,
+    test_class = "com.code_intelligence.jazzer.api.MinimizeTest",
+    runtime_deps = [
+        "//src/main/java/com/code_intelligence/jazzer/runtime",
+    ],
+    deps = [
+        "//src/main/java/com/code_intelligence/jazzer/api",
+        "//src/main/java/com/code_intelligence/jazzer/api:hooks",
+        "//src/main/native/com/code_intelligence/jazzer/driver:jazzer_driver",
+        "@maven//:junit_junit",
+    ],
+)