feat(argv): add schema-checked ordered options and immutable request inputs

Observed second RED at d02b16d: 2038 tests, 10 assertion failures, 0 errors/skips.
Add explicit flag/value/negatable schemas and immutable option occurrences.
Preserve occurrence order and valued false; reject duplicate/mixed-schema ambiguity.
Snapshot legacy maps and mutable values while retaining Boolean flag compatibility.
Do not claim capability discovery or final three-branch integration is complete.

Author: loong10k

src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java

@@ -1,59 +1,79 @@
 package io.github.easy4j.opencli.core;
 
 import io.github.easy4j.opencli.util.OpenCliStrings;
+import java.math.BigDecimal;
+import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Set;
 import lombok.AccessLevel;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.Singular;
 
 /**
- * Structured adapter request. Positional and valued-option contents are literal;
- * command and option identifiers are validated separately.
- * The legacy options map represents a single-valued subset: Boolean values
- * retain their historical presence-only flag semantics.
+ * Structured adapter request with immutable literal values and ordered options.
+ * The legacy options Map retains Boolean presence-only semantics; use
+ * {@link OpenCliOption} for repeated values, valued false and explicit negation.
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  * @since 3.0.0
  */
 @Getter
 @Builder
 public final class OpenCliAdapterCommandRequest {
-
     private final String subcommand;
 
     @Getter(AccessLevel.NONE)
     @Singular("positional")
     private final List<String> positionals;
 
     @Getter(AccessLevel.NONE)
-    @Builder.Default
-    private final Map<String, Object> options = Collections.emptyMap();
+    private final Map<String, Object> options;
+
+    @Getter(AccessLevel.NONE)
+    @Singular("option")
+    private final List<OpenCliOption> orderedOptions;
+
+    /**
+     * Builder customisation snapshots legacy option values before they can be
+     * changed through the caller's Map or a mutable value object.
+     */
+    public static class OpenCliAdapterCommandRequestBuilder {
+        private Map<String, Object> options;
+
+        /** @param source legacy single-value options @return this builder */
+        public OpenCliAdapterCommandRequestBuilder options(Map<String, Object> source) {
+            options = snapshotOptions(source);
+            return this;
+        }
+    }
 
     /** @return an immutable copy of positional values */
     public List<String> getPositionals() {
-        if (Objects.isNull(positionals)) {
-            return Collections.emptyList();
-        }
-        return Collections.unmodifiableList(new ArrayList<>(positionals));
+        return positionals == null ? Collections.emptyList()
+            : Collections.unmodifiableList(new ArrayList<>(positionals));
     }
 
-    /** @return an immutable copy of named options */
+    /** @return an immutable snapshot of legacy options */
     public Map<String, Object> getOptions() {
-        if (Objects.isNull(options)) {
-            return Collections.emptyMap();
-        }
-        return Collections.unmodifiableMap(new LinkedHashMap<>(options));
+        return options == null ? Collections.emptyMap()
+            : Collections.unmodifiableMap(new LinkedHashMap<>(options));
     }
 
-    /**
-     * @return subcommand, then unchanged positional values and named options
-     */
+    /** @return immutable, ordered option occurrences */
+    public List<OpenCliOption> getOrderedOptions() {
+        return orderedOptions == null ? Collections.emptyList()
+            : Collections.unmodifiableList(new ArrayList<>(orderedOptions));
+    }
+
+    /** @return the validated subcommand and complete literal argv */
     public List<String> toSubcommandAndArgs() {
         Objects.requireNonNull(subcommand, "subcommand");
         if (OpenCliStrings.isBlank(subcommand)) {
@@ -64,27 +84,74 @@ public List<String> toSubcommandAndArgs() {
         if (positionals != null) {
             tokens.addAll(OpenCliArgSupport.snapshotValues(positionals, "positionals"));
         }
-        if (Objects.nonNull(options)) {
+        Set<String> legacyFlags = new HashSet<>();
+        if (options != null) {
             for (Map.Entry<String, Object> entry : options.entrySet()) {
-                appendOption(tokens, entry.getKey(), entry.getValue());
+                String flag = appendLegacyOption(tokens, entry.getKey(), entry.getValue());
+                if (flag != null && !legacyFlags.add(flag)) {
+                    throw new IllegalArgumentException("Ambiguous duplicate legacy option identifier");
+                }
+            }
+        }
+        Map<String, OpenCliOptionSchema> seen = new HashMap<>();
+        Map<String, String> wireNames = new HashMap<>();
+        if (orderedOptions != null) {
+            for (int i = 0; i < orderedOptions.size(); i++) {
+                OpenCliOption occurrence = orderedOptions.get(i);
+                if (occurrence == null) {
+                    throw new IllegalArgumentException("orderedOptions[" + i + "] must not be null");
+                }
+                OpenCliOptionSchema schema = occurrence.getSchema();
+                String name = schema.getName();
+                List<String> argv = occurrence.toTokens();
+                String wireName = argv.get(0);
+                if (legacyFlags.contains(name) || legacyFlags.contains(wireName)) {
+                    throw new IllegalArgumentException("Legacy and ordered options must not overlap");
+                }
+                OpenCliOptionSchema previous = seen.put(name, schema);
+                if (previous != null && (!schema.isRepeatable() || !previous.equals(schema))) {
+                    throw new IllegalArgumentException("Repeated option is not allowed by one consistent schema");
+                }
+                String previousCanonical = wireNames.put(wireName, name);
+                if (previousCanonical != null && !previousCanonical.equals(name)) {
+                    throw new IllegalArgumentException("Different schemas emit the same option identifier");
+                }
+                tokens.addAll(argv);
             }
         }
         return tokens;
     }
 
-    private static void appendOption(List<String> target, String name, Object value) {
-        if (OpenCliStrings.isBlank(name) || Objects.isNull(value)) {
-            return;
-        }
-        String flag = name.startsWith("-") ? name.trim() : "--" + name.trim();
-        if (value instanceof Boolean) {
-            if (((Boolean) value).booleanValue()) {
-                target.add(flag);
+    private static Map<String, Object> snapshotOptions(Map<String, Object> source) {
+        if (source == null) { return Collections.emptyMap(); }
+        Map<String, Object> snapshot = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> entry : new LinkedHashMap<>(source).entrySet()) {
+            Object value = entry.getValue();
+            if (value != null) {
+                Class<?> type = value.getClass();
+                if (type != String.class && type != Boolean.class && type != Byte.class
+                    && type != Short.class && type != Integer.class && type != Long.class
+                    && type != Float.class && type != Double.class && type != BigInteger.class
+                    && type != BigDecimal.class) {
+                    value = String.valueOf(value);
+                }
             }
-            return;
+            snapshot.put(entry.getKey(), value);
         }
+        return Collections.unmodifiableMap(snapshot);
+    }
+
+    private static String appendLegacyOption(List<String> target, String name, Object value) {
+        if (OpenCliStrings.isBlank(name) || value == null || Boolean.FALSE.equals(value)) {
+            return null;
+        }
+        String normalized = name.trim();
+        String flag = normalized.startsWith("-") ? normalized : "--" + normalized;
         target.add(flag);
-        target.add(String.valueOf(value));
+        if (!(value instanceof Boolean)) {
+            target.add(String.valueOf(value));
+        }
+        return flag;
     }
 
     /**
@@ -94,16 +161,10 @@ private static void appendOption(List<String> target, String name, Object value)
      * @return a structured request
      */
     public static OpenCliAdapterCommandRequest of(
-        String subcommand,
-        List<String> positionals,
-        Map<String, Object> options) {
+        String subcommand, List<String> positionals, Map<String, Object> options) {
         OpenCliAdapterCommandRequestBuilder b = builder().subcommand(subcommand);
-        if (Objects.nonNull(positionals)) {
-            b.positionals(positionals);
-        }
-        if (Objects.nonNull(options) && !options.isEmpty()) {
-            b.options(new LinkedHashMap<>(options));
-        }
+        if (positionals != null) { b.positionals(positionals); }
+        if (options != null) { b.options(options); }
         return b.build();
     }
 }

src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java

@@ -0,0 +1,73 @@
+package io.github.easy4j.opencli.core;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * One immutable, schema-checked option occurrence. Preserve occurrence ordering
+ * by adding these to a request builder rather than using a Map for repeated flags.
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 3.0.0
+ */
+public final class OpenCliOption {
+    private final OpenCliOptionSchema schema;
+    private final String value;
+    private final boolean negated;
+
+    private OpenCliOption(OpenCliOptionSchema schema, String value, boolean negated) {
+        this.schema = schema;
+        this.value = value;
+        this.negated = negated;
+    }
+
+    /**
+     * @param schema a valued-option definition
+     * @param value non-null value; false is the literal value "false", not absence
+     * @return an occurrence capturing the value immediately
+     */
+    public static OpenCliOption value(OpenCliOptionSchema schema, Object value) {
+        Objects.requireNonNull(schema, "schema");
+        Objects.requireNonNull(value, "value");
+        if (schema.getKind() != OpenCliOptionSchema.Kind.VALUE) {
+            throw new IllegalArgumentException("A flag schema cannot consume a value");
+        }
+        return new OpenCliOption(schema, String.valueOf(value), false);
+    }
+
+    /** @param schema a flag definition @return explicit positive presence */
+    public static OpenCliOption present(OpenCliOptionSchema schema) {
+        Objects.requireNonNull(schema, "schema");
+        if (schema.getKind() == OpenCliOptionSchema.Kind.VALUE) {
+            throw new IllegalArgumentException("A valued option requires a value");
+        }
+        return new OpenCliOption(schema, null, false);
+    }
+
+    /** @param schema a negatable flag definition @return an explicit negative flag */
+    public static OpenCliOption negated(OpenCliOptionSchema schema) {
+        Objects.requireNonNull(schema, "schema");
+        if (schema.getKind() != OpenCliOptionSchema.Kind.NEGATABLE_FLAG) {
+            throw new IllegalArgumentException("This option schema does not declare negation");
+        }
+        return new OpenCliOption(schema, null, true);
+    }
+
+    /** @return immutable input definition */
+    public OpenCliOptionSchema getSchema() { return schema; }
+
+    /** @return the captured value, or null for a flag */
+    public String getValue() { return value; }
+
+    /** @return whether this is explicit negative presence */
+    public boolean isNegated() { return negated; }
+
+    /** @return immutable literal tokens; no quoting or trimming is applied */
+    public List<String> toTokens() {
+        String flag = negated ? "--no-" + schema.getName().substring(2) : schema.getName();
+        return value == null ? Collections.singletonList(flag)
+            : Collections.unmodifiableList(Arrays.asList(flag, value));
+    }
+}

src/main/java/io/github/easy4j/opencli/core/OpenCliOptionSchema.java

@@ -0,0 +1,73 @@
+package io.github.easy4j.opencli.core;
+
+import java.util.Objects;
+import java.util.regex.Pattern;
+
+/**
+ * Explicit option input semantics. Definitions come from a known command contract,
+ * not guesses about a raw argument vector. This is not an output schema.
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 3.0.0
+ */
+public final class OpenCliOptionSchema {
+    /** Input arity and negation semantics. */
+    public enum Kind { FLAG, VALUE, NEGATABLE_FLAG }
+
+    private static final Pattern NAME = Pattern.compile("(?:--[A-Za-z0-9][A-Za-z0-9-]*|-[A-Za-z0-9])");
+    private final String name;
+    private final Kind kind;
+    private final boolean repeatable;
+
+    private OpenCliOptionSchema(String name, Kind kind, boolean repeatable) {
+        Objects.requireNonNull(name, "name");
+        if (!NAME.matcher(name).matches()) {
+            throw new IllegalArgumentException("Option schema requires a valid flag identifier");
+        }
+        if (kind == Kind.NEGATABLE_FLAG && (!name.startsWith("--") || name.startsWith("--no-"))) {
+            throw new IllegalArgumentException("Negatable schema requires a positive long flag identifier");
+        }
+        this.name = name;
+        this.kind = kind;
+        this.repeatable = repeatable;
+    }
+
+    /** @param name flag identifier @return a presence-only, nonrepeatable flag */
+    public static OpenCliOptionSchema flag(String name) {
+        return new OpenCliOptionSchema(name, Kind.FLAG, false);
+    }
+
+    /**
+     * @param name option identifier
+     * @param repeatable whether repeated occurrences are accepted by the command
+     * @return an option taking one literal value per occurrence
+     */
+    public static OpenCliOptionSchema value(String name, boolean repeatable) {
+        return new OpenCliOptionSchema(name, Kind.VALUE, repeatable);
+    }
+
+    /** @param name positive long flag identifier @return a flag supporting explicit negation */
+    public static OpenCliOptionSchema negatableFlag(String name) {
+        return new OpenCliOptionSchema(name, Kind.NEGATABLE_FLAG, false);
+    }
+
+    /** @return canonical flag identifier */
+    public String getName() { return name; }
+
+    /** @return declared input kind */
+    public Kind getKind() { return kind; }
+
+    /** @return whether the command accepts repeated occurrences */
+    public boolean isRepeatable() { return repeatable; }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) { return true; }
+        if (!(other instanceof OpenCliOptionSchema)) { return false; }
+        OpenCliOptionSchema that = (OpenCliOptionSchema) other;
+        return name.equals(that.name) && kind == that.kind && repeatable == that.repeatable;
+    }
+
+    @Override
+    public int hashCode() { return Objects.hash(name, kind, repeatable); }
+}