Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

fix(java): refuse a criteria map whose iteration order is not defined

Adeshina Lasisi253b5c2d8f14
diff --git a/.github/workflows/java.yml b/.github/workflows/java.yml
index 1182858b..cd176143 100644
--- a/.github/workflows/java.yml
+++ b/.github/workflows/java.yml
@@ -179,7 +179,7 @@ jobs:
if: ${{ !cancelled() }}
run: >
python laya-java/scripts/check_test_results.py
- laya-java/laya-java/build/test-results/test --min-tests 933 --allow-aborted
+ laya-java/laya-java/build/test-results/test --min-tests 943 --allow-aborted
# The samples are single-file source programs, deliberately NOT a Gradle module: a
# `samples` subproject would inherit the root build's MavenPublication and
@@ -356,7 +356,7 @@ jobs:
if: ${{ !cancelled() }}
run: >
python laya-java/scripts/check_test_results.py
- laya-java/laya-java/build/test-results/test --min-tests 934 --allow-aborted
+ laya-java/laya-java/build/test-results/test --min-tests 944 --allow-aborted
--require-passed TestJvmVersionTest
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
if: ${{ failure() }}
diff --git a/.github/workflows/release-java.yml b/.github/workflows/release-java.yml
index bb51d071..3d700d43 100644
--- a/.github/workflows/release-java.yml
+++ b/.github/workflows/release-java.yml
@@ -67,7 +67,7 @@ jobs:
# that lane already covered.
- name: Model-free tests
run: ./gradlew --no-daemon test
- # 685 of the 699 registered tests run without a checkpoint. This floor has been raised
+ # 943 of the 960 registered tests run without a checkpoint. This floor has been raised
# as the model-free suite grew -- 440 left 191 of slack, 625 left 60 -- because a floor
# that does not bind is not a gate: under 625 the whole confidence-gate family of 26
# tests could have vanished from this lane with the gate still green.
@@ -83,7 +83,7 @@ jobs:
- name: The suite was not vacuous
run: >
python3 scripts/check_test_results.py laya-java/build/test-results/test
- --min-tests 680 --allow-aborted
+ --min-tests 943 --allow-aborted
- name: Build the jars
run: ./gradlew --no-daemon build -x test
diff --git a/laya-java/README.md b/laya-java/README.md
index da0c7429..dadb6e6d 100644
--- a/laya-java/README.md
+++ b/laya-java/README.md
@@ -55,6 +55,7 @@ import java.nio.file.Path;
import java.util.*;
// Options are POSITIONAL, so use a LinkedHashMap: two orders are two different questions.
+// A HashMap or Map.of is refused rather than silently reordered -- see Option order below.
Map<String, Object> criteria = new LinkedHashMap<>();
criteria.put("refund", "money back for a duplicate charge");
criteria.put("escalate", "pass it to a human");
@@ -476,6 +477,39 @@ and a JVM method call is already synchronous: a hook that wants asynchronous wor
blocks on it — `ship(ctx.results()).toCompletableFuture().join()` — bounded however your runtime
wants, or by `timeout(Duration)`.
+## Option order
+
+A choice's options are positional: option N renders Nth and logit N is read back as the Nth label.
+So the criteria map's iteration order decides both what is asked and how the answer is labelled, and
+a map whose type does not define that order changes both silently. Measured on JDK 17:
+
+| written | `LinkedHashMap` | `HashMap` | `Map.of` |
+|---|---|---|---|
+| `refund, escalate, ignore` | `refund, escalate, ignore` | `ignore, escalate, refund` | varies per JVM |
+
+`HashMap` is exactly reversed here, so `probabilities().get("refund")` would have reported the logit
+that belonged to `ignore`. It is at least reproducible, because `String.hashCode` is specified.
+`Map.of` is worse: it salts its table per JVM, so three runs of one program gave three different
+orders -- the same question answering differently after a restart.
+
+`Question.choice` therefore refuses a map whose contract leaves the order unspecified -- `HashMap`,
+`Map.of`/`Map.copyOf` with two or more options, `ConcurrentHashMap`, `Hashtable`, `WeakHashMap`,
+`IdentityHashMap` -- and names the fix. A `LinkedHashMap`, a `SortedMap`, an unmodifiable view of
+either, or any single-option map is accepted; one option cannot be out of order.
+
+When there is no map to hand, build the question from the options directly and the order cannot be
+lost at all:
+
+```java
+Question q = Question.choiceOf("What does the customer want?",
+ Map.entry("refund", "money back for a duplicate charge"),
+ Map.entry("escalate", "pass it to a human"),
+ Map.entry("ignore", "no action needed"));
+```
+
+Two options sharing a label are refused there too: a map would have kept only the last, asking a
+question with fewer options than were written.
+
## Threads
`Agent.open(model, graph)` leaves the thread count to ONNX Runtime, which is what the Python
diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java
index 84cb4116..cc6555b6 100644
--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java
+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java
@@ -3,9 +3,15 @@ package com.convaiinnovations.laya;
import com.convaiinnovations.laya.json.PythonJson;
import com.convaiinnovations.laya.lang.UnicodeTables;
import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.Hashtable;
+import java.util.IdentityHashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
+import java.util.SortedMap;
+import java.util.WeakHashMap;
+import java.util.concurrent.ConcurrentHashMap;
/**
* One decision to put to the model: its type, its instruction, and the options it chooses between.
@@ -82,10 +88,79 @@ public final class Question {
public static Question choice(String instructions, Map<String, ?> criteria) {
requireInstructions(instructions);
require(criteria != null && !criteria.isEmpty(), "a choice question needs criteria");
+ require(!orderIsUnspecified(criteria),
+ "a choice's options are positional, so the criteria map's iteration order decides "
+ + "what is asked and how the answer is labelled, and "
+ + criteria.getClass().getName() + " does not specify one. Use a LinkedHashMap, or "
+ + "Question.choiceOf(instructions, Map.entry(label, description), ...)");
return new Question(Type.CHOICE, instructions, new LinkedHashMap<>(criteria), null,
null, null);
}
+ /**
+ * A choice built from options in the order they are written, with no map to lose that order.
+ *
+ * <p>The counterpart of {@link #choice} for callers who would otherwise reach for
+ * {@code Map.of}: there is no intermediate collection whose type could reorder the options, so
+ * the Nth argument is the Nth option and index N of {@link #labels} is the label for logit N.
+ *
+ * @throws IllegalArgumentException if two options share a label. A map would have kept only the
+ * last silently, asking a question with fewer options than were written.
+ */
+ @SafeVarargs
+ public static Question choiceOf(String instructions, Map.Entry<String, ?>... options) {
+ requireInstructions(instructions);
+ require(options != null && options.length > 0, "a choice question needs criteria");
+ Map<String, Object> ordered = new LinkedHashMap<>();
+ for (Map.Entry<String, ?> option : options) {
+ require(option != null, "a choice option must not be null");
+ String label = option.getKey();
+ require(label != null && !label.isEmpty(),
+ "a choice option needs a label; give every option a name");
+ // containsKey, not the return of put: a legitimate criterion may be null, and then put
+ // returns null for a duplicate too, so the duplicate would go unreported.
+ require(!ordered.containsKey(label),
+ "duplicate choice label " + PythonJson.repr(label) + "; two options cannot "
+ + "share one label, and a map would have kept only the last");
+ ordered.put(label, option.getValue());
+ }
+ return new Question(Type.CHOICE, instructions, ordered, null, null, null);
+ }
+
+ /**
+ * Whether this map's own contract leaves its iteration order unspecified.
+ *
+ * <p>Measured on JDK 17, with the options written {@code refund, escalate, ignore}: a
+ * {@code HashMap} iterates {@code ignore, escalate, refund} -- exactly reversed, so option 0's
+ * probability would be reported against option 2's label. That much is at least reproducible,
+ * because {@code String.hashCode} is specified. {@code Map.of} is worse: it salts its table per
+ * JVM, so three runs of one program gave three different orders and the same question answers
+ * differently after a restart.
+ *
+ * <p>A denylist rather than an allowlist, because a false refusal breaks working code: Guava's
+ * {@code ImmutableMap} and {@code Collections.unmodifiableMap(aLinkedHashMap)} both iterate in a
+ * defined order this method cannot see, and refusing them would be wrong.
+ */
+ private static boolean orderIsUnspecified(Map<String, ?> criteria) {
+ if (criteria.size() < 2) {
+ return false; // one option cannot be in the wrong order
+ }
+ if (criteria instanceof LinkedHashMap || criteria instanceof SortedMap) {
+ return false;
+ }
+ // By class, not by `instanceof`: LinkedHashMap IS a HashMap, so an instanceof test would
+ // reject the very map this is meant to accept.
+ Class<?> type = criteria.getClass();
+ if (type == HashMap.class || type == Hashtable.class || type == WeakHashMap.class
+ || type == IdentityHashMap.class || type == ConcurrentHashMap.class) {
+ return true;
+ }
+ // `Map.of` and `Map.copyOf` with two or more entries. The class is package-private, so its
+ // name is the only handle on it; it has been stable since the factories arrived in 9. The
+ // single-entry form is a different class and cannot be misordered, so it is not named here.
+ return "java.util.ImmutableCollections$MapN".equals(type.getName());
+ }
+
/** A score over ordered levels, rendered as {@code "level <i>: <criterion>"}. */
public static Question score(String instructions, List<?> levels) {
requireInstructions(instructions);
diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.java
new file mode 100644
index 00000000..618c4f40
--- /dev/null
+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.java
@@ -0,0 +1,148 @@
+package com.convaiinnovations.laya;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.IdentityHashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.concurrent.ConcurrentHashMap;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * A choice's options are positional: option N's description renders Nth and logit N is read back as
+ * the Nth label. So the criteria map's iteration order decides what the model was asked and how its
+ * answer is labelled, and a map whose type does not define that order silently changes both.
+ *
+ * <p>How silent it is, measured on JDK 17:
+ *
+ * <pre>
+ * insertion [refund, escalate, ignore] HashMap [ignore, escalate, refund]
+ * insertion [billing, technical, sales, other] HashMap [other, technical, sales, billing]
+ * </pre>
+ *
+ * Exactly reversed, so {@code probabilities().get("refund")} would have reported the logit that
+ * belonged to {@code ignore}. {@code HashMap} is at least stable run to run, because
+ * {@code String.hashCode} is specified. {@code Map.of} is not: it salts its layout per JVM, so three
+ * runs of one program gave {@code [ignore, escalate, refund]}, {@code [escalate, ignore, refund]}
+ * and {@code [refund, escalate, ignore]} -- the same question answering differently after a restart.
+ */
+class QuestionCriteriaOrderTest {
+
+ /** The labels in the order logit N is read back as label N -- what the order actually decides. */
+ private static List<String> renderedOptions(Question q) {
+ return q.labels();
+ }
+
+ @Test
+ @DisplayName("a LinkedHashMap keeps the caller's order, which is the contract")
+ void linkedHashMapKeepsOrder() {
+ Map<String, Object> c = new LinkedHashMap<>();
+ c.put("refund", "money back for a duplicate charge");
+ c.put("escalate", "pass it to a human");
+ c.put("ignore", "no action needed");
+ assertEquals(List.of("refund", "escalate", "ignore"),
+ renderedOptions(Question.choice("What does the customer want?", c)));
+ }
+
+ @Test
+ @DisplayName("a HashMap is refused, because its order is not the one that was written")
+ void hashMapIsRefused() {
+ Map<String, Object> c = new HashMap<>();
+ c.put("refund", "money back for a duplicate charge");
+ c.put("escalate", "pass it to a human");
+ c.put("ignore", "no action needed");
+ // Proof the hazard is real and not hypothetical: this is the order the model would have been
+ // given, and it is the caller's reversed.
+ assertEquals(List.of("ignore", "escalate", "refund"), new ArrayList<>(c.keySet()));
+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+ () -> Question.choice("What does the customer want?", c));
+ assertTrue(e.getMessage().contains("iteration order"), e.getMessage());
+ assertTrue(e.getMessage().contains("LinkedHashMap"), e.getMessage());
+ }
+
+ @Test
+ @DisplayName("Map.of with two or more options is refused: its order is salted per JVM")
+ void mapOfIsRefused() {
+ Map<String, String> c = Map.of("refund", "money back", "escalate", "to a human");
+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", c));
+ }
+
+ @Test
+ @DisplayName("Map.copyOf is refused too: copying a LinkedHashMap does not keep its order")
+ void mapCopyOfIsRefused() {
+ Map<String, Object> ordered = new LinkedHashMap<>();
+ ordered.put("refund", "money back");
+ ordered.put("escalate", "to a human");
+ // Map.copyOf returns the same salted implementation Map.of does, so the order is gone.
+ assertThrows(IllegalArgumentException.class,
+ () -> Question.choice("Which?", Map.copyOf(ordered)));
+ }
+
+ @Test
+ @DisplayName("the other unordered JDK maps are refused on the same ground")
+ void otherUnorderedMapsAreRefused() {
+ Map<String, Object> chm = new ConcurrentHashMap<>();
+ chm.put("a", "1");
+ chm.put("b", "2");
+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", chm));
+ Map<String, Object> ihm = new IdentityHashMap<>();
+ ihm.put("a", "1");
+ ihm.put("b", "2");
+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", ihm));
+ }
+
+ @Test
+ @DisplayName("a single option is accepted from any map: one option cannot be misordered")
+ void oneOptionIsAlwaysFine() {
+ assertEquals(List.of("only"),
+ renderedOptions(Question.choice("Which?", Map.of("only", "the only option"))));
+ assertEquals(List.of("only"),
+ renderedOptions(Question.choice("Which?", new HashMap<>(Map.of("only", "d")))));
+ }
+
+ @Test
+ @DisplayName("a SortedMap is accepted: its contract defines the order, even if it is not insertion")
+ void sortedMapIsAccepted() {
+ Map<String, Object> c = new TreeMap<>();
+ c.put("refund", "money back");
+ c.put("escalate", "to a human");
+ assertEquals(List.of("escalate", "refund"),
+ renderedOptions(Question.choice("Which?", c)));
+ }
+
+ @Test
+ @DisplayName("an unmodifiable view of a LinkedHashMap is accepted: it delegates iteration")
+ void unmodifiableViewIsAccepted() {
+ Map<String, Object> inner = new LinkedHashMap<>();
+ inner.put("refund", "money back");
+ inner.put("escalate", "to a human");
+ assertEquals(List.of("refund", "escalate"),
+ renderedOptions(Question.choice("Which?", Collections.unmodifiableMap(inner))));
+ }
+
+ @Test
+ @DisplayName("the ordered-entry factory needs no map at all, so order cannot be lost")
+ void orderedEntriesFactory() {
+ Question q = Question.choiceOf("What does the customer want?",
+ Map.entry("refund", "money back for a duplicate charge"),
+ Map.entry("escalate", "pass it to a human"),
+ Map.entry("ignore", "no action needed"));
+ assertEquals(List.of("refund", "escalate", "ignore"), renderedOptions(q));
+ }
+
+ @Test
+ @DisplayName("choiceOf refuses a duplicate label rather than silently dropping an option")
+ void orderedEntriesRefuseDuplicates() {
+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+ () -> Question.choiceOf("Which?", Map.entry("a", "1"), Map.entry("a", "2")));
+ assertTrue(e.getMessage().contains("duplicate"), e.getMessage());
+ }
+}