Add -H:Preserve dependency selection support

common/docs/e2e.md

@@ -29,6 +29,8 @@ Common utility tests cover argument escaping, argument-file conversion, version
 constants, classpath/JAR resource scanning, resource configuration serialization, and schema
 validation. This protects [§FS-common-libraries.1](functional-spec.md#1-shared-native-image-utilities), [§FS-common-libraries.2](functional-spec.md#2-resource-configuration), and
 [§FS-common-libraries.7](functional-spec.md#7-schema-validation).
+They also verify deterministic `-H:Preserve` rendering for resolved paths, including paths with
+spaces and platform-specific separators. [§FS-common-libraries.1](functional-spec.md#1-shared-native-image-utilities).
 
 ### 2.2 Tracing-agent modes and metadata post-processing
 

common/docs/functional-spec.md

@@ -32,16 +32,18 @@ regardless of its vendor label and retaining compatibility behavior when that re
 identified; and centralize Native Image configuration file names and metadata directory names used
 by plugins and tests.
 
-Layer creation uses an immutable, build-tool-neutral artifact selection containing an `all`
-selection, ordered module names, ordered package names, and ordered resolved paths. The shared
-renderer owns the complete `-H:LayerCreate` grammar: `all` renders as an unqualified layer-create
-argument whose contents come from the plugin-supplied classpath, while narrower selections render
-`module=`, `package=`, and `path=` selectors. It rejects blank names and selector values, rejects
-names outside `[A-Za-z0-9._-]+`, and preserves selector order. `all` may be combined with module or
-package selectors; the plugin-supplied classpath still represents the complete dependency graph.
-Native Image version detection recognizes vendor suffixes when applying layer-consumption gates.
-Gradle and Maven must
-resolve their dependency models to paths before calling it.
+Native Image classpath selection uses an immutable, build-tool-neutral artifact value containing
+an `all` selection, ordered module names, ordered package names, and ordered resolved paths. The
+shared layer renderer owns the complete `-H:LayerCreate` grammar: `all` renders as an unqualified
+layer-create argument whose contents come from the plugin-supplied classpath, while narrower
+selections render `module=`, `package=`, and `path=` selectors. The shared Preserve renderer owns
+the equivalent `-H:Preserve` selector grammar and rejects an empty selection. Both renderers
+preserve deterministic module, package, then path order and platform path spelling. The selection
+rejects blank selector values; layer rendering additionally rejects blank names and names outside
+`[A-Za-z0-9._-]+`. `all` may be combined with narrower selectors. Native Image version detection
+recognizes vendor suffixes when applying layer-consumption gates. Gradle and Maven must resolve
+their dependency models to paths before calling either renderer. This shared Preserve behavior
+implements [§root/FS-native-builds.7](../../docs/spec/functional/native-image-builds.md#7-dependency-preservation).
 [§REQ-no-buildtool-apis](requirements.md#req-no-buildtool-apis-common-runtime-libraries-do-not-depend-on-gradle-or-maven-apis).
 
 ## 2. Resource configuration

common/utils/src/main/java/org/graalvm/buildtools/model/resources/NativeImageFlags.java

@@ -50,6 +50,8 @@ public abstract class NativeImageFlags {
     public static final String LAYER_USE = "-H:LayerUse";
     public static final String NO_FALLBACK = "--no-fallback";
     public static final String PGO_INSTRUMENT = "--pgo-instrument";
+    // Dependency Preserve selection is rendered once in common for both adapters. §FS-common-libraries.1.
+    public static final String PRESERVE = "-H:Preserve";
     public static final String QUICK_BUILD = "-Ob";
     public static final String SHARED = "--shared";
     public static final String UNLOCK_EXPERIMENTAL_VMOPTIONS = "-H:+UnlockExperimentalVMOptions";

common/utils/src/main/java/org/graalvm/buildtools/utils/ArtifactSelection.java

@@ -45,7 +45,7 @@
 import java.util.Objects;
 
 /**
- * Immutable build-tool-neutral selection of artifacts for a Native Image layer.
+ * Immutable build-tool-neutral selection of Native Image classpath artifacts.
  * §FS-common-libraries.1.
  */
 public final class ArtifactSelection {
@@ -60,7 +60,7 @@ public ArtifactSelection(boolean all, List<String> modules, List<String> package
         this.packages = validatedStrings("package", packages);
         this.paths = List.copyOf(Objects.requireNonNull(paths, "paths"));
         if (this.paths.stream().anyMatch(Objects::isNull)) {
-            throw new IllegalArgumentException("Layer paths must not contain null values");
+            throw new IllegalArgumentException("Artifact paths must not contain null values");
         }
     }
 
@@ -71,7 +71,7 @@ public static ArtifactSelection empty() {
     private static List<String> validatedStrings(String kind, List<String> values) {
         List<String> copy = List.copyOf(Objects.requireNonNull(values, kind + "s"));
         if (copy.stream().anyMatch(value -> value == null || value.isBlank())) {
-            throw new IllegalArgumentException("Layer " + kind + " selectors must not be blank");
+            throw new IllegalArgumentException("Artifact " + kind + " selectors must not be blank");
         }
         return copy;
     }

common/utils/src/main/java/org/graalvm/buildtools/utils/NativeImagePreserveArguments.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2026, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.buildtools.utils;
+
+import org.graalvm.buildtools.model.resources.NativeImageFlags;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Shared rendering of Native Image Preserve arguments. §FS-common-libraries.1.
+ */
+public final class NativeImagePreserveArguments {
+    private NativeImagePreserveArguments() {
+    }
+
+    public static String renderPreserve(ArtifactSelection selection) {
+        Objects.requireNonNull(selection, "selection");
+        if (selection.isEmpty()) {
+            throw new IllegalArgumentException("Preserve selection must not be empty");
+        }
+        if (selection.isAll() && selection.getModules().isEmpty()
+                && selection.getPackages().isEmpty() && selection.getPaths().isEmpty()) {
+            return NativeImageFlags.PRESERVE + "=all";
+        }
+        List<String> selectors = new ArrayList<>();
+        if (selection.isAll()) {
+            selectors.add("all");
+        }
+        selection.getModules().forEach(module -> selectors.add("module=" + module));
+        selection.getPackages().forEach(packageName -> selectors.add("package=" + packageName));
+        selection.getPaths().forEach(path -> selectors.add("path=" + path));
+        return NativeImageFlags.PRESERVE + "=" + String.join(",", selectors);
+    }
+}

common/utils/src/test/java/org/graalvm/buildtools/utils/NativeImagePreserveArgumentsTest.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2026, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.buildtools.utils;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Verifies the shared Preserve selector grammar and validation. §FS-common-libraries.1. §FS-common-libraries.8.
+ */
+class NativeImagePreserveArgumentsTest {
+    @TempDir
+    Path testDirectory;
+
+    @Test
+    void rendersAllAndMixedSelectorsDeterministically() {
+        assertEquals("-H:Preserve=all", NativeImagePreserveArguments.renderPreserve(
+            new ArtifactSelection(true, List.of(), List.of(), List.of())));
+
+        ArtifactSelection selection = new ArtifactSelection(true,
+            List.of("java.base", "java.logging"),
+            List.of("com.example", "org.example.*"),
+            List.of(Path.of("libs", "one.jar"), Path.of("libs", "two with spaces.jar")));
+
+        assertEquals("-H:Preserve=all,module=java.base,module=java.logging,"
+                + "package=com.example,package=org.example.*,path=libs/one.jar,path=libs/two with spaces.jar",
+            NativeImagePreserveArguments.renderPreserve(selection).replace('\\', '/'));
+    }
+
+    @Test
+    void rendersPathOnlyPlatformSelections() {
+        String argument = NativeImagePreserveArguments.renderPreserve(
+            new ArtifactSelection(false, List.of(), List.of(), List.of(Path.of("build", "dependency.jar"))));
+
+        assertTrue(argument.endsWith("path=" + Path.of("build", "dependency.jar")));
+    }
+
+    @Test
+    void rejectsEmptySelections() {
+        IllegalArgumentException error = assertThrows(IllegalArgumentException.class,
+            () -> NativeImagePreserveArguments.renderPreserve(ArtifactSelection.empty()));
+
+        assertEquals("Preserve selection must not be empty", error.getMessage());
+    }
+
+    @Test
+    void preservesOneSelectorExpressionThroughAnArgumentFile() throws Exception {
+        String argument = NativeImagePreserveArguments.renderPreserve(new ArtifactSelection(false,
+            List.of(), List.of(), List.of(testDirectory.resolve("dependency with spaces.jar"))));
+
+        List<String> converted = NativeImageUtils.convertToArgsFile(List.of(argument), testDirectory, null);
+        Path argsFile = Path.of(converted.get(0).substring(1));
+
+        assertEquals(List.of(NativeImageUtils.escapeArg(argument)), Files.readAllLines(argsFile));
+    }
+}

docs/spec/decisions/README.md

@@ -0,0 +1,3 @@
+# Decisions
+
+- [§DEC-layer-model](layer-model.md#dec-layer-model-native-image-artifact-selection-is-shared-while-build-tool-wiring-stays-native) — Native Image artifact selection is shared while build-tool wiring stays native

docs/spec/decisions/layer-model.md

@@ -1,17 +1,20 @@
-# DEC-layer-model: Native Image layers use shared selection and build-tool-native wiring
+# DEC-layer-model: Native Image artifact selection is shared while build-tool wiring stays native
 
-Native Image layer selection is represented once in `common`, while Gradle and Maven own their
-native task and artifact graphs. This implements [§FS-native-builds.6](../functional/native-image-builds.md#6-layered-images),
+Native Image artifact selection is represented once in `common`, while Gradle and Maven own their
+native task and artifact graphs. Layers and dependency preservation consume the same neutral value.
+This implements [§FS-native-builds.6](../functional/native-image-builds.md#6-layered-images),
+[§FS-native-builds.7](../functional/native-image-builds.md#7-dependency-preservation),
 [§common/FS-common-libraries.1](../../../common/docs/functional-spec.md#1-shared-native-image-utilities),
 [§gradle/FS-plugin-model.2](../../../native-gradle-plugin/docs/functional/plugin-model.md#2-extension-surface), and
-[§maven/FS-goal-surface.6](../../../native-maven-plugin/docs/functional/goal-surface.md#6-layer-creation).
+[§maven/FS-config-model.8](../../../native-maven-plugin/docs/functional/configuration-model.md#8-preserve-dependency-selection).
 
 ## 1. Decision
 
 Gradle exposes named layers outside the binary container and binaries consume typed layer objects.
 Maven exposes a `layer-create` goal that attaches a `nil` artifact and compile goals resolve
 declared `nil` dependencies. Both adapters resolve dependency models to paths before using the
-shared immutable artifact selection and renderer.
+shared immutable artifact selection and renderer. Binary Preserve configuration also resolves
+dependency coordinates to paths before using that selection, without adding raw selector mirrors.
 
 ## 2. Compatibility
 
@@ -22,9 +25,11 @@ opt-in and does not alter existing builds.
 
 ## 3. Boundary
 
-The shared model does not contain Gradle, Maven, Aether, task, project, configuration, or artifact
-types. The plugins do not duplicate dependency resolution: they use Gradle artifact views and
-Maven's project/repository model respectively.
+The shared model is a Native Image selector value, not a layer-owned task model, and may be consumed
+by layer creation, Preserve rendering, and future build-tool-neutral selector grammars. It does not
+contain Gradle, Maven, Aether, task, project, configuration, or artifact types. Layer task and
+artifact wiring remains owned by the layer adapters. The plugins do not duplicate dependency
+resolution: they use Gradle artifact views and Maven's project/repository model respectively.
 [§NGOAL-no-buildtool-duplicates](../non-goals.md#ngoal-no-buildtool-duplicates-the-plugins-do-not-reimplement-capabilities-that-gradle-or-maven-already-provide).
 
 ## 4. GraalVM release support

docs/spec/functional/native-image-builds.md

@@ -89,3 +89,25 @@ permitted but unsupported and must warn that it proceeds at the user's own risk;
 alone does not warn. Native Image layers remain experimental upstream
 ([§DEC-layer-model.4](../decisions/layer-model.md#4-graalvm-release-support)).
 [§GOAL-plugin-parity](../goals.md#goal-plugin-parity-shared-native-image-behavior-remains-consistent-across-gradle-and-maven).
+
+## 7. Dependency preservation
+
+Both plugins must let their approved native-image scopes preserve selected Gradle or Maven
+dependencies by resolving build-tool dependency coordinates, optionally with their transitive
+closure, to concrete classpath paths and rendering one `-H:Preserve=path=...` argument through
+common utilities. The selection is opt-in, preserves transitive dependencies by default, and must
+fail before Native Image starts when coordinates are blank, unresolved, ambiguous, empty, or have
+no usable output. The generated Preserve argument precedes user build arguments so explicit
+pass-through arguments retain their normal precedence.
+
+The first-class build-tool surface is limited to dependency selection because coordinate-to-path
+resolution adds behavior unavailable through static arguments. Users must continue to pass
+`all`, `module=`, `package=`, and explicit `path=` Preserve selectors through normal build arguments,
+protecting [§NGOAL-no-flag-mirroring](../non-goals.md#ngoal-no-flag-mirroring-the-plugins-do-not-add-build-tool-flags-that-only-forward-to-native-image-flags).
+Gradle exposes the selection on every binary option object; Maven exposes it on the
+`compile-no-fork` hierarchy (`compile`, `compile-no-fork`, the deprecated `build` alias, and
+`write-args-file`), not native-test or layer-create goals. Preserve is available with GraalVM 25 and later and does not require the
+experimental-option unlock sequence. Specific dependency selectors are preferred because
+preservation can increase analysis work and image size.
+[§GOAL-plugin-parity](../goals.md#goal-plugin-parity-shared-native-image-behavior-remains-consistent-across-gradle-and-maven),
+[§REQ-backwards-compatibility.2](../requirements.md#2-configuration-compatibility).