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.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
fix(java): what four adversarial reviews found
Adeshina Lasisid2e9d9f0dd59
diff --git a/.github/workflows/java.yml b/.github/workflows/java.ymlindex 747a562a..0903c929 100644--- a/.github/workflows/java.yml+++ b/.github/workflows/java.yml@@ -78,7 +78,13 @@ jobs:# entirely, so the run said nothing about whether the code worked.- name: Model-free fixture drift vs. committedif: ${{ !cancelled() }}- run: python laya-java/scripts/gen_fixtures.py --check --only python_json.json+ # Every family, not one. `--only python_json.json` left lang_detect, lang_tables,+ # presets, router and shortlist gated NOWHERE: a change to laya/ could move the contract+ # those five record and every check stayed green, because the Java tests assert against+ # the stale committed copy -- exactly the failure the fixtures exist to prevent. The+ # generator already leaves checkpoint-backed families alone and reports them unverified,+ # so a bare --check is the right scope.+ run: python laya-java/scripts/gen_fixtures.py --check# The compiled-in Unicode tables are recorded from CPython, so a CPython upgrade that moves# them has to show up here rather than as a routing change nobody attributed.- name: Unicode tables match CPythondiff --git a/laya-java/fixtures/lang_detect.json b/laya-java/fixtures/lang_detect.jsonindex d8a110a9..2746dcfd 100644--- a/laya-java/fixtures/lang_detect.json+++ b/laya-java/fixtures/lang_detect.json@@ -1,5 +1,4 @@{- "notes": "Every output `laya.lang` produces, over a corpus built to break a port.\n\n WHY EACH CASE IS HERE. The corpus is not a sample of real traffic; every entry exercises a\n branch that a reimplementation gets wrong by default:\n\n * the four regexes, which no other language spells the same way -- Java's `\\w` admits\n combining marks that Python's does not, and `String.split` drops trailing empty fields\n where Python's keeps them;\n * `str.lower()`, which is not `String.toLowerCase` (final sigma) and not one-to-one (U+0130);\n * `str.isspace()`, which `Character.isWhitespace` disagrees with on four code points, two of\n them the no-break spaces a pasted ticket is full of;\n * `round(x, 4)` and `round(x)`, both of which are half-to-EVEN on the exact binary value;\n * dict insertion order, which decides the script profile's order and every tie between two\n languages with the same score;\n * and the structured-state scans, where a long English stack trace must not outvote a short\n foreign message, and a name field must not pull an English ticket off the English model.\n\n Each case records the full output of `state_text`, `detect_script`, `script_profile`,\n `latin_profile`, `analyse` and `is_english`. String cases also record every internal helper,\n so a failure names the step that broke rather than only the verdict.\n ","thresholds": {"non_en_diacritic_rate": 0.02,"english_rescue_diacritic_rate": 0.06,diff --git a/laya-java/fixtures/router.json b/laya-java/fixtures/router.jsonindex 4028b758..feacb013 100644--- a/laya-java/fixtures/router.json+++ b/laya-java/fixtures/router.json@@ -1,5 +1,4 @@{- "notes": "Everything `laya.router` decides before a checkpoint is loaded.\n\n The routing decision is the part of the router that is pure logic, and it is the part that\n decides whether a request reaches a checkpoint that can read it. The English checkpoint does\n not degrade gently off English -- 0.100 on 20-option Hindi intent against 0.050 for random,\n while reporting high confidence -- so a wrong route is a wrong answer delivered confidently.\n\n The `reason` strings are recorded too, not just the model. They are user-visible, they go into\n API responses, and they are built with two Python formats that Java spells differently:\n `%r`, which is CPython's repr, and `%.0f`, which rounds halves to EVEN where\n `String.format(\"%.0f\", ...)` rounds them up. One of the reasons interpolates the mixed\n segment, a slice of the caller's own text, so both formats see arbitrary input.\n ","bundle_repo": "convaiinnovations/laya","default_models": {"english": [@@ -121,6 +120,21 @@},"multilingual2": {"error": "unknown model 'multilingual2'; choose one of ['english', 'multilingual', 'typed-decisions'] (or an alias: ['decisions', 'default', 'en', 'laya', 'laya-multilingual', 'laya-typed-decisions', 'ml', 'multi', 'typed', 'typed_decisions'])"+ },+ " english": {+ "ok": "english"+ },+ "english ": {+ "ok": "english"+ },+ " multilingual": {+ "ok": "multilingual"+ },+ "typed-decisions ": {+ "ok": "typed-decisions"+ },+ " en": {+ "ok": "english"}},"resolve_model_spec": {@@ -194,7 +208,27 @@"laya-x": null,"en-US": null,"typed decisions": null,- "multilingual2": null+ "multilingual2": null,+ " english": [+ "convaiinnovations/laya",+ null+ ],+ "english ": [+ "convaiinnovations/laya",+ null+ ],+ " multilingual": [+ "convaiinnovations/laya",+ "multilingual"+ ],+ "typed-decisions ": [+ "convaiinnovations/laya",+ "typed-decisions"+ ],+ " en": [+ "convaiinnovations/laya",+ null+ ]},"typed_decision_workflows": {"agent_trace_observability": [@@ -461,6 +495,34 @@[0,false+ ],+ [+ " en",+ true+ ],+ [+ "en ",+ true+ ],+ [+ "en ",+ true+ ],+ [+ " en-US",+ true+ ],+ [+ "C ",+ null+ ],+ [+ " und",+ null+ ],+ [+ "fr ",+ false]],"question_schema": [diff --git a/laya-java/fixtures/shortlist.json b/laya-java/fixtures/shortlist.jsonindex 5efb112e..ccfbe0f0 100644--- a/laya-java/fixtures/shortlist.json+++ b/laya-java/fixtures/shortlist.json@@ -1,5 +1,4 @@{- "notes": "`laya.shortlist`'s ranking, its edge cases, and what it hands to `predict`.\n\n Choice options share one `head_max_len`, so a large label set leaves a few tokens per label.\n Shortlisting embeds the state and each option, keeps the top k, and runs ONE predict on the\n reduced set. The parts that need gating are not the embedding -- a caller supplies that -- but\n the ranking rules around it, and each of them is a place a port goes wrong silently:\n\n * the sort is STABLE and descending, so a tie keeps the earlier label. `argsort` without\n `kind=\"mergesort\"` reorders ties, which changes which labels survive at the cut.\n * the score is a SIGNED cosine, not a similarity floor. A label scoring 0 -- no signal, or a\n non-finite vector treated as none -- outranks one scoring negative, and k drops the\n negatives first.\n * a zero-norm query scores everything 0, so the kept set is the first k in criteria order.\n * non-finite components become 0 rather than propagating or raising.\n * k >= the label count is a passthrough: the labels come back in criteria order, scores are\n None, and the embedder is NEVER called.\n ","score_decimals": 12,"default_k": 20,"embed_dim": 8,@@ -963,6 +962,33 @@]}],+ "nan_ranking": {+ "criteria": {+ "a": "A",+ "b": "B",+ "c": "C"+ },+ "k": 2,+ "option_texts": [+ "a: A",+ "b: B",+ "c: C"+ ],+ "query_text": "state",+ "sims": [+ "nan",+ 0.0,+ 0.0+ ],+ "labels": [+ "b",+ "c"+ ],+ "scores": [+ 0.0,+ 0.0+ ]+ },"cosine": [{"name": "ordinary",@@ -1249,6 +1275,40 @@]}],+ "cache_counters": [+ {+ "texts": [+ "a",+ "a",+ "b"+ ],+ "size": 2,+ "maxsize": 64,+ "hits": 0,+ "misses": 3+ },+ {+ "texts": [+ "a",+ "b",+ "c"+ ],+ "size": 3,+ "maxsize": 64,+ "hits": 2,+ "misses": 4+ },+ {+ "texts": [+ "q",+ "a"+ ],+ "size": 4,+ "maxsize": 64,+ "hits": 3,+ "misses": 5+ }+ ],"refusals": [{"name": "k-zero",diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Presets.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Presets.javaindex 2de876d3..6dde99bd 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Presets.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Presets.java@@ -1,5 +1,6 @@package com.convaiinnovations.laya;+import com.convaiinnovations.laya.json.PythonJson;import com.convaiinnovations.laya.lang.UnicodeTables;import java.util.Collections;import java.util.LinkedHashMap;@@ -209,10 +210,17 @@ public final class Presets {return null;}Set<String> named = new LinkedHashSet<>();- for (Question question : questions.values()) {- if (question != null) {- collectBacktickedFields(question.instructions(), named);+ for (Map.Entry<String, Question> entry : questions.entrySet()) {+ // A null question is refused rather than skipped. Skipping it would answer with the+ // field the REMAINING questions name, which looks like a correct answer and is not --+ // the reference raises here, and a caller who dropped a question by setting it to+ // null should hear about it rather than get a plausible field name back.+ if (entry.getValue() == null) {+ throw new IllegalArgumentException(+ "question " + PythonJson.repr(entry.getKey()) + " is null; remove the"+ + " entry rather than setting it to null");}+ collectBacktickedFields(entry.getValue().instructions(), named);}return named.size() == 1 ? named.iterator().next() : null;}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.javaindex f8667afa..84cb4116 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@@ -1,6 +1,7 @@package com.convaiinnovations.laya;import com.convaiinnovations.laya.json.PythonJson;+import com.convaiinnovations.laya.lang.UnicodeTables;import java.util.ArrayList;import java.util.LinkedHashMap;import java.util.List;@@ -123,8 +124,13 @@ public final class Question {trueLabel = labels.get("true");require(falseLabel != null && trueLabel != null,"noul labels must map exactly 'false' and 'true' to distinct non-empty strings");- falseLabel = falseLabel.trim();- trueLabel = trueLabel.trim();+ // Python's strip, not Java's trim. `trim` removes only code points at or below+ // U+0020, so a label of a single no-break space would survive it, pass the+ // non-empty check below, and render into the model's input as whitespace -- a+ // different token sequence from the one the reference produces, which refuses the+ // label outright.+ falseLabel = UnicodeTables.strip(falseLabel);+ trueLabel = UnicodeTables.strip(trueLabel);require(!falseLabel.isEmpty() && !trueLabel.isEmpty() && !falseLabel.equals(trueLabel),"noul labels must map exactly 'false' and 'true' to distinct non-empty strings");}@@ -287,7 +293,11 @@ public final class Question {* a confident-looking distribution over the options. Python refuses the same input.*/private static void requireInstructions(String instructions) {- require(instructions != null && !instructions.isBlank(),+ // UnicodeTables.isBlank, not String.isBlank: the reference tests `not ins.strip()`, and+ // Python's strip treats U+00A0, U+0085, U+2007 and U+202F as whitespace where+ // Character.isWhitespace does not. An instruction of a single no-break space is+ // therefore refused by the reference and would have been accepted here.+ require(instructions != null && !UnicodeTables.isBlank(instructions),"instructions must not be empty; add the text the model should answer");}diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.javaindex e34bd6e9..46ec4715 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java@@ -2,6 +2,7 @@ package com.convaiinnovations.laya;import com.convaiinnovations.laya.json.PythonJson;import com.convaiinnovations.laya.lang.LanguageDetection;+import com.convaiinnovations.laya.lang.UnicodeTables;import java.io.IOException;import java.io.UncheckedIOException;import java.nio.file.Path;@@ -182,6 +183,7 @@ public final class Router implements AutoCloseable, Predictor {private final Checkpoint checkpoint;private final Slot slot;+ /** Guarded by {@link Router#lock}: see {@link #close()} for why a plain flag is not enough. */private boolean released;private Lease(Checkpoint checkpoint, Slot slot) {@@ -191,11 +193,16 @@ public final class Router implements AutoCloseable, Predictor {/** The agent, valid until this lease is closed. */public Agent agent() {- if (released) {- throw new IllegalStateException("this lease on " + checkpoint.wireName()- + " has been released");+ lock.lock();+ try {+ if (released) {+ throw new IllegalStateException("this lease on " + checkpoint.wireName()+ + " has been released");+ }+ return slot.agent;+ } finally {+ lock.unlock();}- return slot.agent;}/** Which checkpoint this is. */@@ -203,14 +210,34 @@ public final class Router implements AutoCloseable, Predictor {return checkpoint;}- /** Release it. Idempotent, so a try-with-resources around an early return is safe. */+ /**+ * Release it. Idempotent, so a try-with-resources around an early return is safe.+ *+ * <p>The flag and the lease count move together under {@link Router#lock}. A plain+ * check-then-set is not enough: two threads closing the SAME lease both read+ * {@code released == false}, both decrement, and the count reaches zero while another+ * lease is still open -- so the agent is closed under a caller that is still using it,+ * which is the single failure this whole mechanism exists to prevent.+ */@Overridepublic void close() {- if (released) {- return;+ Agent toClose = null;+ lock.lock();+ try {+ if (released) {+ return;+ }+ released = true;+ slot.leases--;+ if (slot.leases <= 0 && slot.retired && slot.ownsClosing) {+ toClose = slot.agent;+ }+ } finally {+ lock.unlock();+ }+ if (toClose != null) {+ toClose.close();}- released = true;- release(slot);}}@@ -534,7 +561,11 @@ public final class Router implements AutoCloseable, Predictor {if (name == null) {return null;}- String key = name.trim().toLowerCase(Locale.ROOT);+ // UnicodeTables.strip, not String.trim: trim only removes code points at or below+ // U+0020, so a name padded with a no-break space or an ideographic space -- which a+ // config file pasted from a browser or produced by a CJK input method carries routinely+ // -- would fail to resolve where the reference resolves it.+ String key = UnicodeTables.pythonLower(UnicodeTables.strip(name));Checkpoint alias = ALIASES.get(key);if (alias != null) {return alias;@@ -578,9 +609,27 @@ public final class Router implements AutoCloseable, Predictor {* would silently change model.*/public static String matchTypedDecisionsWorkflow(Map<String, ?> questions) {- Set<String> ids = questions == null ? Set.of() : questions.keySet();+ if (questions == null || questions.isEmpty()) {+ return null;+ }+ // Copied into a set that tolerates null, and tested member by member. `Set.of(...)`+ // throws on a null argument to `containsAll`, so a question map with a null id -- which+ // a HashMap allows -- would abort the whole route where the reference merely fails to+ // match and carries on to detection.+ Set<String> ids = new LinkedHashSet<>(questions.keySet());for (Map.Entry<String, Set<String>> entry : TYPED_DECISION_WORKFLOWS.entrySet()) {- if (entry.getValue().size() == ids.size() && entry.getValue().containsAll(ids)) {+ Set<String> signature = entry.getValue();+ if (signature.size() != ids.size()) {+ continue;+ }+ boolean matches = true;+ for (String id : ids) {+ if (id == null || !signature.contains(id)) {+ matches = false;+ break;+ }+ }+ if (matches) {return entry.getKey();}}@@ -629,7 +678,12 @@ public final class Router implements AutoCloseable, Predictor {if (value == null) {return null;}- String code = String.valueOf(value).trim().toLowerCase(Locale.ROOT);+ // Python's strip and Python's lower, for the reason given on normaliseName. Getting this+ // wrong is worse here than there: a `lang` of "en" with a trailing ideographic space+ // would route to the multilingual checkpoint while the reason string still reported that+ // the caller asked for English, and a padded "C " would pin every request to+ // multilingual instead of falling through to detection.+ String code = UnicodeTables.pythonLower(UnicodeTables.strip(String.valueOf(value)));if (code.isEmpty()) {return null;}@@ -851,14 +905,20 @@ public final class Router implements AutoCloseable, Predictor {}// Someone else is building this one. Wait for them rather than build a second copy.await(waitFor);- if (waitFor.error != null) {- throw waitFor.error;+ RuntimeException failure = waitFor.error;+ if (failure != null) {+ // Wrapped per waiter, with the builder's error as the cause. Rethrowing the one+ // instance gave every waiter a stack trace of frames it never executed -- the+ // builder's -- and let concurrent handlers mutate one Throwable's suppressed+ // list, which Throwable does not support.+ throw new IllegalStateException("loading the " + checkpoint.wireName()+ + " checkpoint failed on the thread that was building it", failure);}}}private Slot build(Checkpoint checkpoint, InFlight inflight) {- List<Checkpoint> evicted = List.of();+ List<Agent> toClose = new ArrayList<>();Slot built;try {// The build itself runs outside `lock`, so routing and eviction are not stalled for@@ -880,6 +940,7 @@ public final class Router implements AutoCloseable, Predictor {lock.unlock();}Agent agent = create(checkpoint);+ boolean duplicate = false;lock.lock();try {Slot attached = slots.get(checkpoint);@@ -889,18 +950,25 @@ public final class Router implements AutoCloseable, Predictor {touch(checkpoint);attached.leases++;built = attached;- agent.close();+ duplicate = true;} else {built = new Slot(agent, true);built.leases++;slots.put(checkpoint, built);order.add(checkpoint);- evicted = evictLocked();+ evictLocked(toClose);}- finish(checkpoint, inflight);} finally {+ // ALWAYS, even if eviction threw. Skipping it left the new slot published+ // with a lease that nothing could release -- so the agent could never be+ // retired or closed -- and left every waiter parked on a latch for a+ // checkpoint that had in fact loaded.+ finish(checkpoint, inflight);lock.unlock();}+ if (duplicate) {+ toClose.add(agent);+ }} finally {buildLock.unlock();}@@ -918,10 +986,20 @@ public final class Router implements AutoCloseable, Predictor {}throw failure;}- if (!evicted.isEmpty()) {- // Nothing to dispatch here, but keeping the list is what lets a caller see which- // checkpoints left: `loaded()` after a load is the observable form of it.- assert evicted.size() <= Checkpoint.values().length;+ // Outside every lock. Closing a native session can be slow, and doing it under `lock`+ // stalled callers asking for an ALREADY-RESIDENT checkpoint -- which is the one thing the+ // fast path in `acquire` exists to keep fast. Measured at 1.3 s for an unrelated lease+ // behind one slow close.+ try {+ closeAll(toClose);+ } catch (RuntimeException | Error failure) {+ // The new slot is already published and holds the lease this call took. Throwing+ // without releasing it would strand that lease forever: nothing else can reach it,+ // so the agent could never be retired or closed -- an unreachable, unclosable native+ // session. The caller is about to get an exception instead of the lease, so giving it+ // back here is exactly right.+ release(built);+ throw failure;}return built;}@@ -989,9 +1067,8 @@ public final class Router implements AutoCloseable, Predictor {** @return the checkpoints that left*/- private List<Checkpoint> evictLocked() {+ private List<Checkpoint> evictLocked(List<Agent> toClose) {List<Checkpoint> evicted = new ArrayList<>();- List<Agent> toClose = new ArrayList<>();while (order.size() > maxLoaded) {Checkpoint victim = order.remove(0);Slot slot = slots.remove(victim);@@ -1013,7 +1090,6 @@ public final class Router implements AutoCloseable, Predictor {}}}- closeAll(toClose);return evicted;}@@ -1044,7 +1120,11 @@ public final class Router implements AutoCloseable, Predictor {try {requireOpen();Slot previous = slots.put(checkpoint, new Slot(agent, false));- if (previous != null) {+ // Not when it is the SAME agent. `attach`ing the instance `load` just returned is+ // exactly what the javadoc invites, and retiring the previous slot would close the+ // very agent the caller is being told the router will never close -- leaving a live+ // slot holding a closed session that nothing can ever replace.+ if (previous != null && previous.agent != agent) {retire(previous, toClose);}touch(checkpoint);@@ -1110,7 +1190,9 @@ public final class Router implements AutoCloseable, Predictor {* <p>Waits for an in-flight build of that checkpoint only, so an unrelated cold load does not* stall this call.*- * @return the checkpoints that were freed, which is empty when it was not resident+ * @return the checkpoints this router let go of, which is empty when it was not resident.+ * "Let go of" and "closed" are not the same thing when a lease is outstanding: the slot+ * is dropped immediately and its agent closes when the last lease is released.*/public List<Checkpoint> unload(String name) {Checkpoint checkpoint = normaliseName(name);@@ -1180,7 +1262,14 @@ public final class Router implements AutoCloseable, Predictor {}}- /** How many checkpoints may be resident at once; {@link #attach} and {@link #preload} raise it. */+ /**+ * How many checkpoints may be resident at once.+ *+ * <p>A high-water mark, not a window: {@link #attach} and {@link #preload} raise it to fit+ * what they make resident and nothing lowers it again, so detaching later leaves the raised+ * ceiling in place. That is the reference's behaviour and is kept deliberately; a caller who+ * needs the original ceiling back should build a new router.+ */public int maxLoaded() {lock.lock();try {diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Shortlist.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Shortlist.javaindex 5630203e..36dac425 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Shortlist.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Shortlist.java@@ -83,6 +83,21 @@ public final class Shortlist {public Ranking {labels = List.copyOf(labels);scores = scores == null ? null : scores.clone();+ // Validated, because this is public API and the components can contradict each other:+ // two labels with one score, or a total below the number kept, give any consumer+ // zipping the two an out-of-bounds or a silently misattributed score.+ if (total < labels.size()) {+ throw new IllegalArgumentException(String.format(+ "total is %d but %d labels were kept", total, labels.size()));+ }+ if (passthrough && scores != null) {+ throw new IllegalArgumentException("a passthrough ranking has no scores");+ }+ if (!passthrough && (scores == null || scores.length != labels.size())) {+ throw new IllegalArgumentException(String.format(+ "%d labels need %d scores, got %s", labels.size(), labels.size(),+ scores == null ? "none" : Integer.toString(scores.length)));+ }}/** The scores, copied, or null when nothing was dropped. */@@ -96,6 +111,12 @@ public final class Shortlist {public record Shortlisted(Prediction prediction, Map<String, Ranking> shortlist) {public Shortlisted {+ if (prediction == null) {+ throw new IllegalArgumentException("prediction must not be null");+ }+ if (shortlist == null) {+ throw new IllegalArgumentException("shortlist must not be null");+ }shortlist = Collections.unmodifiableMap(new LinkedHashMap<>(shortlist));}}@@ -232,14 +253,31 @@ public final class Shortlist {double[][] matrix = embeddings(embedder, texts);double[] sims = cosine(matrix[0], matrix, 1);- // A stable descending sort: ties keep the earlier label, which decides which labels- // survive the cut whenever two score the same -- and with a zero-norm query every label- // scores the same.+ // A stable descending sort, with NaN LAST.+ //+ // Both halves of that are load-bearing. Stability makes a tie keep the earlier label,+ // which decides which labels survive whenever two score the same -- and with a zero-norm+ // query every label scores the same. And NaN has to be pushed to the end by hand, because+ // `Double.compare` ranks it as the LARGEST double, which in a descending comparator puts+ // it FIRST: the opposite end from `np.argsort`, which sorts NaN last. A score is NaN when+ // a vector's norm overflows to infinity, and getting its position wrong does not merely+ // misreport a number -- it changes WHICH LABELS survive the cut, so the model is asked a+ // different question.Integer[] order = new Integer[total];for (int i = 0; i < total; i++) {order[i] = i;}- Arrays.sort(order, (left, right) -> Double.compare(sims[right], sims[left]));+ Arrays.sort(order, (left, right) -> {+ double a = sims[left];+ double b = sims[right];+ boolean leftIsNaN = Double.isNaN(a);+ boolean rightIsNaN = Double.isNaN(b);+ if (leftIsNaN || rightIsNaN) {+ // Equal when both are NaN, so the stable sort keeps their original order.+ return leftIsNaN && rightIsNaN ? 0 : (leftIsNaN ? 1 : -1);+ }+ return Double.compare(b, a);+ });List<String> kept = new ArrayList<>(checked);double[] scores = new double[checked];@@ -412,6 +450,7 @@ public final class Shortlist {}double[][] out = new double[keys.size()][];Set<String> wanted = new LinkedHashSet<>();+ int hitsThisCall = 0;lock.lock();try {for (int i = 0; i < keys.size(); i++) {@@ -419,28 +458,51 @@ public final class Shortlist {if (row != null) {out[i] = row;hits++;+ hitsThisCall++;} else {wanted.add(keys.get(i));}}- misses += wanted.size();+ // Per OCCURRENCE, not per distinct text, which is how the reference counts it.+ // `hits` is already per occurrence, so counting misses per distinct text would+ // put the two counters on different bases and `hits + misses` would stop equalling+ // the number of texts looked up -- which is exactly what anyone sizing a cache+ // from these numbers assumes.+ misses += keys.size() - hitsThisCall;} finally {lock.unlock();}if (wanted.isEmpty()) {- return out;+ return copyRows(out);}// Deduplicated and embedded in ONE call, outside the lock, so a cold cache costs what// the unwrapped embedder costs and a slow embed does not block other callers' hits.List<String> toEmbed = new ArrayList<>(wanted);double[][] fresh = embeddings(delegate, toEmbed);++ // Rows of one width cannot be stacked against rows of another, and `rank` reads the+ // result as one matrix. A changed embedder -- a swapped or reloaded bi-encoder -- is+ // the way this happens. The reference REFUSES the call here, before writing anything,+ // and that ordering is the point: caching the new width first would leave a cache+ // that fails on every later call touching both widths until someone clears it, which+ // turns a refused call into a permanently broken cache.+ int width = fresh.length == 0 ? -1 : fresh[0].length;lock.lock();try {+ if (width > 0 && !rows.isEmpty()) {+ int held = rows.values().iterator().next().length;+ if (width != held) {+ throw new IllegalArgumentException(String.format(+ "the embedder returned dim %d, but the cache holds dim %d;"+ + " call cacheClear() if the model behind it changed",+ width, held));+ }+ }for (int i = 0; i < toEmbed.size(); i++) {rows.put(toEmbed.get(i), fresh[i]);- }- while (rows.size() > maxSize) {- rows.remove(rows.keySet().iterator().next());+ while (rows.size() > maxSize) {+ rows.remove(rows.keySet().iterator().next());+ }}} finally {lock.unlock();@@ -454,6 +516,22 @@ public final class Shortlist {out[i] = byText.get(keys.get(i));}}+ return copyRows(out);+ }++ /**+ * A fresh row per entry, so a caller cannot reach into the cache.+ *+ * <p>The reference stacks its rows into a new array on every return, so its cache is+ * immune to a caller editing what it handed back. Returning the stored arrays directly+ * would let one caller's write corrupt every later lookup of that text -- and alias the+ * same array into several rows when a text repeats within one call.+ */+ private static double[][] copyRows(double[][] rows) {+ double[][] out = new double[rows.length][];+ for (int i = 0; i < rows.length; i++) {+ out[i] = rows[i] == null ? null : rows[i].clone();+ }return out;}diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/json/PythonJson.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/json/PythonJson.javaindex 35f3acc4..f3b82fa8 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/json/PythonJson.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/json/PythonJson.java@@ -259,8 +259,14 @@ public final class PythonJson {*/public static String percent0(double fraction) {double scaled = 100.0 * fraction;- if (Double.isNaN(scaled) || Double.isInfinite(scaled)) {- return repr(scaled);+ if (Double.isNaN(scaled)) {+ return "nan";+ }+ if (Double.isInfinite(scaled)) {+ // CPython's %-formatting spells these in lower case, which is NOT how `repr` spells+ // them: `'%.0f' % float('nan')` is "nan" where `repr` gives "NaN". Latent today --+ // both call sites are finite by construction -- and wrong the moment one is not.+ return scaled > 0 ? "inf" : "-inf";}// Math.rint is IEEE ties-to-even, which is the rule; a long keeps a share above 2^31.return Long.toString((long) Math.rint(scaled));diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/PresetsTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/PresetsTest.javaindex 11fa36f3..71e5d1b6 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/PresetsTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/PresetsTest.java@@ -230,6 +230,22 @@ class PresetsTest {assertNull(Presets.stateField(new LinkedHashMap<>()));}+ @Test+ @DisplayName("a null question is refused, not quietly skipped")+ void stateFieldRefusesANullQuestion() {+ // Skipping it would answer with the field the REMAINING questions name, which looks like+ // a correct answer and is not. The reference raises here, and a caller who dropped a+ // question by setting it to null should hear about it rather than get a plausible field+ // name back.+ Map<String, Question> questions = new LinkedHashMap<>();+ questions.put("intent", Question.noul("Does `message` ask for a refund?"));+ questions.put("dropped", null);+ IllegalArgumentException failure = assertThrows(IllegalArgumentException.class,+ () -> Presets.stateField(questions));+ assertTrue(failure.getMessage().contains("dropped"),+ "the message must name the offending question: " + failure.getMessage());+ }+@Test@DisplayName("each call returns a fresh mutable map, so a caller can edit one safely")void presetsAreFreshAndMutable() {diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionRenderingTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionRenderingTest.javaindex d160b5d8..c67c8232 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionRenderingTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionRenderingTest.java@@ -165,4 +165,47 @@ final class QuestionRenderingTest {assertEquals(2, Question.Type.NOUL.code());assertEquals("choice", Question.Type.CHOICE.wireName());}++ @org.junit.jupiter.api.Test+ @DisplayName("blankness follows Python's whitespace set, not Java's")+ void blanknessUsesPythonsWhitespace() {+ // The reference refuses an instruction whose strip() is empty, and Python's strip treats+ // U+00A0, U+0085, U+2007 and U+202F as whitespace where Character.isWhitespace -- and so+ // String.isBlank and String.trim -- do not. An instruction of a single no-break space is+ // therefore refused by the reference, and was accepted here: the model would have been+ // shown "noul question: " and answered it anyway with a confident-looking distribution.+ int[] blanks = {0x20, 0xA0, 0x85, 0x2007, 0x202F};+ for (int cp : blanks) {+ String blank = new String(Character.toChars(cp));+ org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class,+ () -> Question.noul(blank),+ "an instruction of U+" + Integer.toHexString(cp) + " must be refused");+ }+ // U+200B is NOT whitespace to Python either, so it stays a legitimate instruction: the+ // rule is Python's set, not "anything invisible".+ String zeroWidth = new String(Character.toChars(0x200B));+ assertEquals(zeroWidth, Question.noul(zeroWidth).instructions());+ }++ @org.junit.jupiter.api.Test+ @DisplayName("noul labels are stripped with Python's whitespace set")+ void noulLabelsUsePythonsStrip() {+ // Same root cause on the label path. trim leaves a no-break space in place, so the label+ // passes the non-empty check and renders whitespace into the model's input -- a different+ // token sequence from the reference, which refuses the label.+ String nbsp = new String(Character.toChars(0xA0));+ String narrow = new String(Character.toChars(0x202F));+ java.util.Map<String, String> blankLabel = new LinkedHashMap<>();+ blankLabel.put("false", nbsp);+ blankLabel.put("true", "yes");+ org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class,+ () -> Question.noul("Is this urgent?", null, null, blankLabel),+ "a label of one no-break space must be refused");++ java.util.Map<String, String> padded = new LinkedHashMap<>();+ padded.put("false", nbsp + "no");+ padded.put("true", "yes" + narrow);+ assertEquals(java.util.List.of("no", "yes"),+ Question.noul("Is this urgent?", null, null, padded).labels());+ }}diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterLifecycleTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterLifecycleTest.javaindex dd2db716..e8e2fa17 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterLifecycleTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterLifecycleTest.java@@ -3,6 +3,7 @@ package com.convaiinnovations.laya;import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertFalse;import static org.junit.jupiter.api.Assertions.assertNotEquals;+import static org.junit.jupiter.api.Assertions.assertNotNull;import static org.junit.jupiter.api.Assertions.assertNull;import static org.junit.jupiter.api.Assertions.assertSame;import static org.junit.jupiter.api.Assertions.assertThrows;@@ -440,10 +441,8 @@ final class RouterLifecycleTest {assertTrue(go.await(10, TimeUnit.SECONDS));router.load("multilingual");thrown.add(new AssertionError("the load should have failed"));- } catch (UncheckedIOException expected) {- thrown.add(expected);- } catch (Throwable other) {- thrown.add(other);+ } catch (Throwable failure) {+ thrown.add(failure);}}, "failing-load-" + i);worker.start();@@ -458,10 +457,32 @@ final class RouterLifecycleTest {assertFalse(worker.isAlive(), worker.getName() + " never finished");}assertEquals(threads, thrown.size());+ // One caller built and sees the IOException wrapper directly; the rest waited and are+ // handed a per-thread wrapper carrying it as the cause. The builder's own exception+ // instance is deliberately NOT rethrown on the waiters: that gave every waiter a+ // stack trace of frames it never ran, and let concurrent handlers mutate one+ // Throwable's suppressed list, which Throwable does not support.+ int builders = 0;+ int waiters = 0;+ java.util.Set<Throwable> distinct = java.util.Collections.newSetFromMap(+ new java.util.IdentityHashMap<>());for (Throwable failure : thrown) {- assertTrue(failure instanceof UncheckedIOException,- "every caller must see the failure, got " + failure);+ distinct.add(failure);+ if (failure instanceof UncheckedIOException) {+ builders++;+ } else {+ assertTrue(failure instanceof IllegalStateException,+ "a waiter must see a wrapper, got " + failure);+ assertTrue(failure.getCause() instanceof UncheckedIOException,+ "the wrapper must carry the builder's failure as its cause, got "+ + failure.getCause());+ waiters++;+ }}+ assertEquals(1, builders, "exactly one caller does the building");+ assertEquals(threads - 1, waiters, "and the rest wait on it");+ assertEquals(threads, distinct.size(),+ "each caller must get its OWN throwable, not one shared instance");assertEquals(1, agents.attemptsOf(Checkpoint.MULTILINGUAL),"six callers must share one failed attempt, not pay for six");assertEquals(List.of(), router.loaded());@@ -575,6 +596,164 @@ final class RouterLifecycleTest {return ((Answer.Noul) answer).noul();}+ @Test+ @DisplayName("a throwing close during eviction does not strand the new checkpoint")+ void aThrowingCloseDoesNotStrandTheNewAgent() throws IOException {+ // Eviction closes the victim. If that close throws, the publish of the NEW slot has+ // already happened -- so skipping the bookkeeping that follows left its lease stuck at+ // one forever, which meant the agent could never be retired or closed: an unreachable,+ // unclosable native session, and every waiter told the load failed when it had not.+ TinyCheckpoint.RecordingSession angry = new TinyCheckpoint.RecordingSession() {+ @Override+ public void close() {+ super.close();+ throw new IllegalStateException("a native close can fail");+ }+ };+ List<TinyCheckpoint.RecordingSession> built = new ArrayList<>();+ Router.AgentFactory factory = checkpoint -> {+ if (checkpoint == Checkpoint.ENGLISH) {+ return TinyCheckpoint.agent(checkpointRoot, angry);+ }+ TinyCheckpoint.RecordingSession session = new TinyCheckpoint.RecordingSession();+ built.add(session);+ return TinyCheckpoint.agent(checkpointRoot, session);+ };+ try (Router router = Router.builder().agents(factory).maxLoaded(1).build()) {+ router.load("english");+ assertThrows(IllegalStateException.class, () -> router.load("multilingual"),+ "the failing close is surfaced, not swallowed");++ // The point: multilingual really is resident, and it is still CLOSABLE.+ assertEquals(List.of(Checkpoint.MULTILINGUAL), router.loaded());+ assertEquals(1, built.size());+ assertFalse(built.get(0).closed, "nothing has released it yet");+ assertEquals(List.of(Checkpoint.MULTILINGUAL), router.unload("multilingual"));+ assertTrue(built.get(0).closed,+ "the new agent must be closable; a stranded lease would keep it open forever");+ }+ }++ @Test+ @DisplayName("closing one lease twice from two threads cannot close an agent another holds")+ void closingALeaseTwiceIsSafeUnderARace() throws Exception {+ // A plain check-then-set on the released flag loses this race: both threads see it unset,+ // both decrement, the count reaches zero while lease B is open, and the agent is closed+ // under a caller still using it -- the single failure the lease mechanism exists to stop.+ for (int attempt = 0; attempt < 200; attempt++) {+ StubAgents agents = new StubAgents();+ try (Router router = routerWith(agents).maxLoaded(2).build()) {+ Router.Lease a = router.lease("english");+ Router.Lease b = router.lease("english");+ TinyCheckpoint.RecordingSession session =+ agents.lastSession(Checkpoint.ENGLISH);+ router.unload("english"); // retired, not closed: two leases are open+ assertFalse(session.closed);++ int racers = 4;+ CountDownLatch go = new CountDownLatch(1);+ List<Thread> threads = new ArrayList<>();+ for (int i = 0; i < racers; i++) {+ Thread thread = new Thread(() -> {+ try {+ assertTrue(go.await(10, TimeUnit.SECONDS));+ } catch (InterruptedException interrupted) {+ Thread.currentThread().interrupt();+ return;+ }+ a.close();+ }, "closer-" + i);+ thread.start();+ threads.add(thread);+ }+ go.countDown();+ for (Thread thread : threads) {+ thread.join(TimeUnit.SECONDS.toMillis(10));+ }+ assertFalse(session.closed,+ "lease b is still open, so the agent must not be closed (attempt "+ + attempt + ")");+ assertEquals(session, agents.lastSession(Checkpoint.ENGLISH));+ b.close();+ assertTrue(session.closed, "and closing the last lease does close it");+ }+ }+ }++ @Test+ @DisplayName("attaching the agent the router already holds does not close it")+ void attachingTheSameInstanceIsSafe() {+ // The javadoc invites exactly this: "register an already-built agent instead of loading a+ // second copy". Retiring the previous slot closed the very agent being attached, leaving+ // a live slot holding a closed session that nothing could ever replace.+ StubAgents agents = new StubAgents();+ // Managed by hand rather than with try-with-resources, because what is being asserted is+ // what close() does -- and an explicit close() inside a resource block is a -Xlint:try+ // warning, which is an error here.+ Router router = routerWith(agents).maxLoaded(2).build();+ Agent english = router.load("english");+ TinyCheckpoint.RecordingSession session = agents.lastSession(Checkpoint.ENGLISH);+ assertSame(english, router.attach("english", english));+ assertFalse(session.closed, "attaching the same instance must not close it");+ assertSame(english, router.load("english"), "and it is still the resident agent");+ assertEquals(1, router.loaded().size());+ // it is caller-owned now, so the router must leave it alone even on close()+ router.close();+ assertFalse(session.closed, "ownership moved to the caller, so the router leaves it");+ english.close();+ assertTrue(session.closed, "and the owner can still close it");+ }++ @Test+ @DisplayName("a slow close does not stall a lease on an already-resident checkpoint")+ void aSlowCloseDoesNotStallOtherCallers() throws Exception {+ // Closing under the registry lock stalled every other caller, including ones asking for a+ // checkpoint already in memory -- which is precisely what the fast path exists to keep+ // fast. Measured at 1.3 s for an unrelated lease behind one slow close.+ CountDownLatch closing = new CountDownLatch(1);+ CountDownLatch release = new CountDownLatch(1);+ TinyCheckpoint.RecordingSession slow = new TinyCheckpoint.RecordingSession() {+ @Override+ public void close() {+ closing.countDown();+ try {+ assertTrue(release.await(10, TimeUnit.SECONDS));+ } catch (InterruptedException interrupted) {+ Thread.currentThread().interrupt();+ }+ super.close();+ }+ };+ Router.AgentFactory factory = checkpoint -> checkpoint == Checkpoint.ENGLISH+ ? TinyCheckpoint.agent(checkpointRoot, slow)+ : TinyCheckpoint.agent(checkpointRoot, new TinyCheckpoint.RecordingSession());+ try (Router router = Router.builder().agents(factory).maxLoaded(2).build()) {+ router.load("english");+ router.load("typed-decisions");+ // On its own thread: the eviction's close now happens outside every lock, which is+ // the fix being tested -- so this call itself blocks until the close finishes.+ Thread evicting = new Thread(() -> router.load("multilingual"), "evicting-load");+ evicting.start();++ assertTrue(closing.await(10, TimeUnit.SECONDS), "the slow close never started");+ CountDownLatch leased = new CountDownLatch(1);+ Thread other = new Thread(() -> {+ try (Router.Lease lease = router.lease("typed-decisions")) {+ assertNotNull(lease.agent());+ leased.countDown();+ }+ }, "resident-lease");+ other.start();+ assertTrue(leased.await(5, TimeUnit.SECONDS),+ "a lease on a resident checkpoint blocked behind an unrelated slow close");+ release.countDown();+ other.join(TimeUnit.SECONDS.toMillis(10));+ evicting.join(TimeUnit.SECONDS.toMillis(10));+ assertFalse(evicting.isAlive(), "the evicting load never finished");+ assertTrue(slow.closed, "and the slow close did complete");+ }+ }+@Test@DisplayName("close frees what the router built and refuses further loads")void closeFreesAndSeals() {diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterTest.javaindex 1d0349e0..b308f03f 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterTest.java@@ -191,10 +191,28 @@ class RouterTest {}@Test- @DisplayName("matchTypedDecisionsWorkflow tolerates null and empty")+ @DisplayName("matchTypedDecisionsWorkflow tolerates null, empty, and a null question id")void matchWorkflowHandlesNothing() {assertNull(Router.matchTypedDecisionsWorkflow(null));assertNull(Router.matchTypedDecisionsWorkflow(new LinkedHashMap<>()));++ // A HashMap permits a null key, and `Set.of(...).containsAll` throws on one. With five+ // keys the cardinality check passes first, so the whole route would abort on input the+ // reference routes normally -- it simply fails to match and carries on to detection.+ Map<String, Question> withNullId = new java.util.HashMap<>();+ for (String id : List.of("action", "needs_review", "outcome", "risk")) {+ withNullId.put(id, Question.noul("Is this " + id + "?"));+ }+ withNullId.put(null, Question.noul("Is this urgent?"));+ assertEquals(5, withNullId.size(), "the cardinality must match a real workflow");+ assertNull(Router.matchTypedDecisionsWorkflow(withNullId),+ "a null id matches no workflow, and must not throw");++ // and the route completes rather than aborting+ Router.RouteDecision decided = Router.builder().autoTaskDetection(true).build()+ .route("I cannot log in to my account at all today", withNullId);+ assertEquals(Router.Checkpoint.ENGLISH, decided.model());+ assertNull(decided.workflow());}@TestFactorydiff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/ShortlistTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/ShortlistTest.javaindex 1704dfb4..3d1eacb5 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/ShortlistTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/ShortlistTest.java@@ -1,8 +1,10 @@package com.convaiinnovations.laya;+import static org.junit.jupiter.api.Assertions.assertArrayEquals;import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertFalse;import static org.junit.jupiter.api.Assertions.assertNotNull;+import static org.junit.jupiter.api.Assertions.assertNotSame;import static org.junit.jupiter.api.Assertions.assertNull;import static org.junit.jupiter.api.Assertions.assertSame;import static org.junit.jupiter.api.Assertions.assertThrows;@@ -301,7 +303,9 @@ class ShortlistTest {@DisplayName("a non-finite component becomes zero rather than spreading or raising")List<DynamicTest> nonFiniteCleaning() {List<DynamicTest> tests = new ArrayList<>();+ java.util.Set<String> kinds = new java.util.LinkedHashSet<>();for (Object entry : list(fixture().get("nonfinite"))) {+ kinds.add((String) map(entry).get("name"));Map<String, Object> row = map(entry);String name = (String) row.get("name");tests.add(DynamicTest.dynamicTest(name, () -> {@@ -316,6 +320,13 @@ class ShortlistTest {}double[][] cleaned = Shortlist.embeddings(texts -> raw, List.of("q", "d"));List<Object> expectedRows = list(row.get("cleaned"));+ // Shape first: the inner loops below walk the EXPECTED rows, so an extra or+ // missing produced row would otherwise be invisible.+ assertEquals(expectedRows.size(), cleaned.length, name + ": row count");+ for (int r = 0; r < expectedRows.size(); r++) {+ assertEquals(list(expectedRows.get(r)).size(), cleaned[r].length,+ name + ": width of row " + r);+ }for (int r = 0; r < expectedRows.size(); r++) {List<Object> values = list(expectedRows.get(r));for (int c = 0; c < values.size(); c++) {@@ -325,6 +336,11 @@ class ShortlistTest {}}));}+ // A floor, with the reason the rows exist: an empty fixture key would otherwise generate+ // no tests and the suite would stay green. Each kind is a different non-finite value, and+ // each has to become zero rather than propagate.+ assertTrue(kinds.containsAll(List.of("nan", "posinf", "neginf", "all-nan")),+ "every non-finite kind must be covered, got " + kinds);return tests;}@@ -390,6 +406,21 @@ class ShortlistTest {assertEquals(original, questions, name + ": the caller's map was modified");}));}+ // Floors, with the reason: one reduced choice proves the subsetting, one passthrough+ // proves the embedder is skipped, and without them an empty key generates no tests at all.+ int reduced = 0;+ int passthrough = 0;+ for (Object entry : list(fixture().get("predicts"))) {+ for (Object ranking : map(map(entry).get("shortlist")).values()) {+ if (Boolean.TRUE.equals(map(ranking).get("passthrough"))) {+ passthrough++;+ } else {+ reduced++;+ }+ }+ }+ assertTrue(reduced >= 1, "no case actually reduces a choice");+ assertTrue(passthrough >= 1, "no case exercises the passthrough");return tests;}@@ -468,6 +499,8 @@ class ShortlistTest {Shortlist.Ranking ranking = Shortlist.rank("state", question,texts -> new double[texts.size()][EMBED_DIM], 3);assertEquals(List.of("a", "b", "c"), ranking.labels());+ assertEquals(3, ranking.scores().length, "three kept labels, three scores -- asserted"+ + " before the loop, or an empty array would make it vacuous");for (double score : ranking.scores()) {assertEquals(0.0, score);}@@ -541,7 +574,12 @@ class ShortlistTest {assertEquals(1, batchSizes.get(1),"a repeat must embed the new query alone, not the options again");for (int row = 1; row < 4; row++) {- assertSame(first[row], second[row], "the cached row must be the one handed back");+ // Equal contents, but NOT the same array. The reference stacks its rows into a fresh+ // array on every return, so its cache cannot be reached through what it hands back;+ // an earlier version of this test asserted identity and was asserting the defect.+ assertArrayEquals(first[row], second[row], "the cached vector must come back");+ assertNotSame(first[row], second[row],+ "the cache must hand out a copy, not its own row");}Map<String, Long> info = cached.cacheInfo();@@ -565,9 +603,144 @@ class ShortlistTest {}, 64);double[][] rows = cached.embed(List.of("a", "a", "a", "b"));assertEquals(List.of(2), batchSizes, "four texts, two distinct, one embedding call of two");- assertSame(rows[0], rows[1], "the repeats share one row");- assertSame(rows[0], rows[2]);- assertFalse(rows[0] == rows[3]);+ assertArrayEquals(rows[0], rows[1], "the repeats carry the same vector");+ assertArrayEquals(rows[0], rows[2]);+ assertNotSame(rows[0], rows[1], "but not the same array: each row is its own storage,"+ + " as numpy's stack gives");+ assertFalse(java.util.Arrays.equals(rows[0], rows[3]), "and b is a different vector");+ }++ @Test+ @DisplayName("a NaN score ranks LAST, as numpy's argsort puts it, not first")+ void nanRanksLast() {+ // Java's Double.compare ranks NaN as the LARGEST double, so a descending comparator puts+ // it FIRST -- the opposite end from numpy. That is not a cosmetic difference: the kept+ // labels change, so the reduced criteria handed to the model are a different question.+ // A score is NaN whenever a vector's norm overflows to infinity.+ Map<String, Object> recorded = map(fixture().get("nan_ranking"));+ Map<String, Object> criteria = new LinkedHashMap<>(map(recorded.get("criteria")));+ int k = ((Number) recorded.get("k")).intValue();++ Shortlist.Embedder nan = texts -> {+ double[][] rows = new double[texts.size()][];+ for (int i = 0; i < texts.size(); i++) {+ String text = texts.get(i);+ if (text.startsWith("b:")) {+ rows[i] = new double[] {1.0, 0.0};+ } else if (text.startsWith("c:")) {+ rows[i] = new double[] {0.0, 1.0};+ } else {+ rows[i] = new double[] {1e200, 1e200};+ }+ }+ return rows;+ };+ Shortlist.Ranking ranking = Shortlist.rank("state", criteria, nan, k);+ List<String> expected = new ArrayList<>();+ for (Object label : list(recorded.get("labels"))) {+ expected.add((String) label);+ }+ assertEquals(expected, ranking.labels(),+ "the NaN-scored label must be dropped first, not kept first");+ List<Object> recordedScores = list(recorded.get("scores"));+ for (int i = 0; i < recordedScores.size(); i++) {+ assertScore(number(recordedScores.get(i)), ranking.scores()[i], "score " + i);+ }+ assertEquals(k, ranking.scores().length, "one score per kept label -- asserted before"+ + " the loop, or an empty array would make it vacuous");+ for (double score : ranking.scores()) {+ assertFalse(Double.isNaN(score), "no NaN may survive the cut here");+ }+ }++ @Test+ @DisplayName("the cache refuses a changed embedding width and stays usable")+ void cacheRefusesAWidthChange() {+ // Rows of one width cannot be stacked against rows of another, and rank reads the result+ // as one matrix. The reference REFUSES the call before writing anything, and the ordering+ // is the point: caching the new width first leaves a cache that fails on every later call+ // touching both widths until someone clears it -- a refused call turned into a+ // permanently broken cache.+ int[] width = {3};+ Shortlist.CachedEmbedder cached = Shortlist.cached(texts -> {+ double[][] rows = new double[texts.size()][width[0]];+ for (int r = 0; r < rows.length; r++) {+ rows[r][0] = 1.0;+ }+ return rows;+ }, 64);+ assertEquals(3, cached.embed(List.of("a"))[0].length);++ width[0] = 5;+ IllegalArgumentException failure = assertThrows(IllegalArgumentException.class,+ () -> cached.embed(List.of("b")));+ assertTrue(failure.getMessage().contains("dim 5"), failure.getMessage());+ assertTrue(failure.getMessage().contains("cacheClear"),+ "the message must say how to recover: " + failure.getMessage());++ assertEquals(1L, cached.cacheInfo().get("size"),+ "the refused row must not have been cached");+ assertEquals(3, cached.embed(List.of("a"))[0].length,+ "and the cache must still serve what it already held");+ cached.cacheClear();+ assertEquals(5, cached.embed(List.of("b"))[0].length, "after a clear, the new width works");+ }++ @TestFactory+ @DisplayName("the cache counters match the reference, call by call")+ List<DynamicTest> cacheCountersMatchTheReference() {+ // hits and misses are both per OCCURRENCE in the reference, so hits + misses equals the+ // number of texts looked up. Counting misses per DISTINCT text -- the obvious reading of+ // "embed each text once" -- breaks that identity on the first repeated text, and anyone+ // sizing a cache from these numbers would be reading two different bases against+ // each other.+ List<DynamicTest> tests = new ArrayList<>();+ Shortlist.CachedEmbedder cached = Shortlist.cached(ShortlistTest::stubEmbed, 64);+ int looked = 0;+ for (Object entry : list(fixture().get("cache_counters"))) {+ Map<String, Object> call = map(entry);+ List<String> texts = new ArrayList<>();+ for (Object text : list(call.get("texts"))) {+ texts.add((String) text);+ }+ looked += texts.size();+ int expectedLooked = looked;+ tests.add(DynamicTest.dynamicTest(texts.toString(), () -> {+ cached.embed(texts);+ Map<String, Long> info = cached.cacheInfo();+ assertEquals(((Number) call.get("size")).longValue(), info.get("size"), "size");+ assertEquals(((Number) call.get("maxsize")).longValue(), info.get("maxsize"));+ assertEquals(((Number) call.get("hits")).longValue(), info.get("hits"), "hits");+ assertEquals(((Number) call.get("misses")).longValue(), info.get("misses"),+ "misses must count occurrences, not distinct texts");+ assertEquals(expectedLooked, info.get("hits") + info.get("misses"),+ "hits + misses must equal the texts looked up so far");+ }));+ }+ // A repeated text within one call is the whole point of per-occurrence counting, so it is+ // the floor. An empty key would otherwise generate nothing.+ boolean hasRepeat = false;+ for (Object entry : list(fixture().get("cache_counters"))) {+ List<Object> texts = list(map(entry).get("texts"));+ if (new java.util.HashSet<>(texts).size() < texts.size()) {+ hasRepeat = true;+ }+ }+ assertTrue(hasRepeat, "no recorded call repeats a text, so per-occurrence counting is"+ + " indistinguishable from per-distinct counting");+ assertTrue(tests.size() >= 3, "only " + tests.size() + " recorded calls");+ return tests;+ }++ @Test+ @DisplayName("editing what the cache returned cannot corrupt the cache")+ void returnedRowsAreIsolated() {+ Shortlist.CachedEmbedder cached = Shortlist.cached(ShortlistTest::stubEmbed, 64);+ double[][] first = cached.embed(List.of("a"));+ double original = first[0][0];+ first[0][0] = 99.0;+ assertEquals(original, cached.embed(List.of("a"))[0][0],+ "a caller's write must not reach the cached vector");}@Testdiff --git a/laya-java/scripts/gen_fixtures.py b/laya-java/scripts/gen_fixtures.pyindex 050469c4..629088f9 100644--- a/laya-java/scripts/gen_fixtures.py+++ b/laya-java/scripts/gen_fixtures.py@@ -25,6 +25,12 @@ import sysimport unicodedataHERE = os.path.dirname(os.path.abspath(__file__))+# Where the checkpoint-backed families look for weights when LAYA_FIXTURE_CHECKPOINTS is unset.+# Repo-relative on purpose: this was one developer's absolute home directory, which made WHETHER+# a family regenerates at all a property of whose machine ran the script -- and wrote that path+# into a committed skip marker in an open-source repository.+DEFAULT_CHECKPOINT_ROOT = os.path.normpath(+ os.path.join(HERE, "..", ".work", "checkpoints"))FIXTURES = os.path.normpath(os.path.join(HERE, "..", "fixtures"))REPO = os.path.normpath(os.path.join(HERE, "..", ".."))if REPO not in sys.path:@@ -414,7 +420,6 @@ def lang_detect():return rowreturn {- "notes": lang_detect.__doc__,"thresholds": {"non_en_diacritic_rate": lang.NON_EN_DIACRITIC_RATE,"english_rescue_diacritic_rate": lang.ENGLISH_RESCUE_DIACRITIC_RATE,@@ -482,8 +487,7 @@ def presets():# replace the defaults rather than merge with them.out["email_questions_custom"] = mod.email_questions({"ops": "incidents and deploys", "legal": "contracts and compliance"})- out["email_questions_empty_categories"] = mod.email_questions({}) \- if mod.email_questions({}) is not None else None+ out["email_questions_empty_categories"] = mod.email_questions({})return out@@ -581,7 +585,12 @@ def router():names = ["english", "multilingual", "typed-decisions"]aliases = sorted(mod._ALIASES)hostile_names = ["", " ", "ENGLISH", " english ", "English", "nope", "laya-x", "en-US",- "typed decisions", "multilingual2"]+ "typed decisions", "multilingual2",+ # Padded with whitespace Python strips and Java's String.trim does NOT:+ # a no-break space, an ideographic space, a narrow no-break space, NEL.+ # A config file pasted from a browser, or a CJK input method, produces these.+ "\u00a0english", "english\u00a0", "\u3000multilingual",+ "typed-decisions\u202f", "\u0085en"]def normalise(name):try:@@ -599,6 +608,10 @@ def router():"fr", "FR", "pt-BR", "pt_BR.UTF-8", "zh-Hans", "de", "x","c", "C", "POSIX", "C.UTF-8", "und", "zxx", "mul", "UND",".", "-", "_", ".UTF-8", "-US", 1, True, 0,+ # Padded with whitespace Python strips and Java's String.trim does not. The first is the+ # one that matters most: "en" plus an ideographic space must still route to English, and+ # a padded "C" must still abstain rather than pin every request to multilingual.+ "\u00a0en", "en\u00a0", "en\u3000", "\u3000en-US", "C\u00a0", "\u202fund", "fr\u0085",]schemas = [@@ -764,7 +777,6 @@ def router():}return {- "notes": router.__doc__,"bundle_repo": mod.BUNDLE_REPO,"default_models": {k: list(mod._split(v)) for k, v in mod.DEFAULT_MODELS.items()},"standalone_models": {k: list(mod._split(v)) for k, v in mod.STANDALONE_MODELS.items()},@@ -910,6 +922,38 @@ def shortlist():else mod._subset_criteria(criteria, labels)),})+ # A NaN score, which numpy's argsort sorts to the END. Java's Double.compare ranks NaN as+ # the LARGEST double, so a descending comparator puts it FIRST unless that is handled -- a+ # different set of labels then survives the cut and the model is asked a different question.+ def nan_embed(texts):+ import numpy as np+ rows = []+ for text in texts:+ if text.startswith("a:") or text == "a" or text.endswith(" a"):+ rows.append([1e200, 1e200])+ elif ":" in text and text.split(":")[0] == "b":+ rows.append([1.0, 0.0])+ elif ":" in text and text.split(":")[0] == "c":+ rows.append([0.0, 1.0])+ else:+ rows.append([1e200, 1e200])+ return np.asarray(rows, dtype=np.float64)++ nan_criteria = {"a": "A", "b": "B", "c": "C"}+ nan_labels, nan_scores = mod.shortlist_choice(+ "state", nan_criteria, nan_embed, 2, return_scores=True)+ nan_case = {+ "criteria": nan_criteria,+ "k": 2,+ "option_texts": mod._option_texts(mod._criteria_items(nan_criteria)),+ "query_text": mod._query_text("state", None),+ "sims": [_round_score(v) for v in mod._cosine(+ nan_embed([mod._query_text("state", None)])[0],+ nan_embed(mod._option_texts(mod._criteria_items(nan_criteria))))],+ "labels": list(nan_labels),+ "scores": None if nan_scores is None else [_round_score(v) for v in nan_scores],+ }+record("large-top-5", states["string"], criteria_large, 5)record("large-top-1", states["string"], criteria_large, 1)record("large-top-16-of-17", states["string"], criteria_large, 16)@@ -1036,15 +1080,16 @@ def shortlist():})return {- "notes": shortlist.__doc__,"score_decimals": _SCORE_DECIMALS,"default_k": mod.DEFAULT_SHORTLIST_K,"embed_dim": _EMBED_DIM,"embed_probe": {text: [float(v) for v in _stub_embed([text])[0]]for text in ["", "a", "refund: money back", states["string"]]},"cases": cases,+ "nan_ranking": nan_case,"cosine": cosine_cases,"nonfinite": nonfinite,+ "cache_counters": _cache_counter_cases(),"refusals": refusals,"predicts": predicts,}@@ -1065,6 +1110,26 @@ def shortlist():_SCORE_DECIMALS = 12+def _cache_counter_cases():+ """What `cached_embed_fn`'s counters report, call by call.++ Recorded because the two counters are on the same basis and it is easy to put them on+ different ones: `hits` counts OCCURRENCES and so does `misses`, so `hits + misses` equals the+ number of texts looked up. Counting misses per DISTINCT text instead -- which is the obvious+ reading of "embed each text once" -- breaks that identity on the very first repeated text.+ """+ from laya import shortlist as mod++ calls = []+ embedder = mod.cached_embed_fn(_stub_embed, maxsize=64)+ for texts in (["a", "a", "b"], ["a", "b", "c"], ["q", "a"]):+ embedder(list(texts))+ info = embedder.cache_info()+ calls.append({"texts": list(texts), "size": info["size"], "maxsize": info["maxsize"],+ "hits": info["hits"], "misses": info["misses"]})+ return calls++def _round_score(value):"""A cosine rounded to a precision BLAS blocking cannot move, or tagged when non-finite."""value = float(value)@@ -1096,7 +1161,7 @@ def tokenizer_ids():from laya.common import encode_textrig = os.environ.get("LAYA_FIXTURE_CHECKPOINTS",- "/Users/nombauser/Documents/nomba-dev/laya-e2e/checkpoints")+ DEFAULT_CHECKPOINT_ROOT)out = {}for name in ("english", "multilingual"):root = os.path.join(rig, name)@@ -1120,7 +1185,11 @@ def tokenizer_ids():if not found:out[name] = {"skipped": "no tokenizer.json under %s" % root}continue- directory = os.path.dirname(sorted(found, key=len)[0])+ # A TOTAL order: `key=len` alone ties on equal-length candidates and the winner+ # then depends on filesystem walk order -- which decides the tokenizer directory, and+ # therefore every recorded id in this family. That is the same class of bug the+ # comment above describes having been hit once already.+ directory = os.path.dirname(sorted(found, key=lambda path: (len(path), path))[0])from transformers import AutoTokenizertok = AutoTokenizer.from_pretrained(directory)raw = json.load(open(os.path.join(directory, "tokenizer.json"), encoding="utf-8"))@@ -1270,7 +1339,7 @@ def sequences():from laya.common import build_sequencerig = os.environ.get("LAYA_FIXTURE_CHECKPOINTS",- "/Users/nombauser/Documents/nomba-dev/laya-e2e/checkpoints")+ DEFAULT_CHECKPOINT_ROOT)out = {}for name in ("english", "multilingual"):root = os.path.join(rig, name)@@ -1339,7 +1408,7 @@ def decode_answers():from laya.common import clamp_temperature, resolve_lang_temperaturesrig = os.environ.get("LAYA_FIXTURE_CHECKPOINTS",- "/Users/nombauser/Documents/nomba-dev/laya-e2e/checkpoints")+ DEFAULT_CHECKPOINT_ROOT)def row(values):return np.asarray(values, dtype=np.float32)@@ -1639,7 +1708,7 @@ def predict_golden():graph = os.environ.get("LAYA_ONNX_GRAPH")model = os.environ.get("LAYA_PREDICT_MODEL", "multilingual")rig = os.environ.get("LAYA_FIXTURE_CHECKPOINTS",- "/Users/nombauser/Documents/nomba-dev/laya-e2e/checkpoints")+ DEFAULT_CHECKPOINT_ROOT)if not graph or not os.path.exists(graph):return {"skipped": "set LAYA_ONNX_GRAPH to an exported laya.onnx to record this family"}from laya.onnx_agent import ONNXAgent@@ -1736,11 +1805,24 @@ def main(argv=None):"that is supposed to have the checkpoints")args = parser.parse_args(argv)- os.makedirs(FIXTURES, exist_ok=True)+ # A --only naming no family used to exit 0 and print "fixtures match laya", so one typo --+ # a hyphen for an underscore, a renamed file, a family dropped from FAMILIES -- turned the+ # whole gate into a no-op that actively asserted the opposite.+ if args.only:+ unknown = sorted(set(args.only) - set(FAMILIES))+ if unknown:+ print("gen_fixtures: no such fixture family: %s\n known families: %s"+ % (", ".join(unknown), ", ".join(sorted(FAMILIES))), file=sys.stderr)+ return 2++ if not args.check:+ os.makedirs(FIXTURES, exist_ok=True)stale, written, unverified = [], [], []+ examined = 0for filename, build in sorted(FAMILIES.items()):if args.only and filename not in args.only:continue+ examined += 1path = os.path.join(FIXTURES, filename)payload = build()fresh = render(payload)@@ -1776,8 +1858,15 @@ def main(argv=None):print("gen_fixtures: run laya-java/scripts/gen_fixtures.py and commit the result",file=sys.stderr)return 1- print("gen_fixtures: fixtures match laya%s"- % (" (%d family/families unverified)" % len(unverified) if unverified else ""))+ if examined == 0:+ # Belt and braces with the --only validation above: reporting a match after+ # comparing nothing is the one outcome this gate must never produce.+ print("gen_fixtures: no fixture family was examined, so nothing was checked",+ file=sys.stderr)+ return 2+ print("gen_fixtures: %d family/families match laya%s"+ % (examined,+ " (%d unverified)" % len(unverified) if unverified else ""))return 0for line in written:print("wrote " + line)diff --git a/laya-java/scripts/gen_language_tables.py b/laya-java/scripts/gen_language_tables.pyindex e886d5d3..01e60104 100755--- a/laya-java/scripts/gen_language_tables.py+++ b/laya-java/scripts/gen_language_tables.py@@ -27,6 +27,13 @@ TARGET = os.path.join("LanguageTables.java")+# The control characters Java spells with a letter escape; everything else below U+0020 gets an+# octal escape, because a backslash-u escape is translated before the lexer sees it.+_JAVA_LETTER_ESCAPES = {+ "\b": "\\b", "\t": "\\t", "\n": "\\n", "\f": "\\f", "\r": "\\r",+}++def quote(text):"""A Java string literal, with every non-ASCII character escaped so the file stays ASCII."""out = ['"']@@ -35,6 +42,16 @@ def quote(text):out.append('\\"')elif ch == "\\":out.append("\\\\")+ elif ch in _JAVA_LETTER_ESCAPES:+ out.append(_JAVA_LETTER_ESCAPES[ch])+ elif ch < " ":+ # Below U+0020 a backslash-u escape is NOT safe: javac translates those before the+ # file is lexed, so a newline or carriage return would terminate the string literal+ # and the generated file would fail to compile with "unclosed string literal" rather+ # than anything that names the cause. An octal escape is handled by the lexer, not+ # the pre-pass, so it survives. Latent today -- no stopword or script name holds a+ # control character -- and a build break the first time one does.+ out.append("\\%03o" % ord(ch))elif " " <= ch <= "~":out.append(ch)else:@@ -45,6 +62,22 @@ def quote(text):return "".join(out)+# A `new int[] {...}` or `Set.of(...)` literal compiles to instructions inside whatever method+# holds it, and a JVM method body may not exceed 65,535 bytes. Everything this generator emits+# lands in one `<clinit>`, measured at about 7,800 bytes today -- so there is room, but no signal+# if that changes. The sibling generator guards its own tables for exactly this reason; the+# failure mode without a guard is "code too large" from javac, which names no cause.+MAX_LITERALS = 20000+++def _check_budget(name, count):+ if count > MAX_LITERALS:+ raise SystemExit(+ "gen_language_tables: %s would emit %d literals into the class initialiser, over the "+ "%d this generator will allow. Split it into its own factory method before "+ "regenerating." % (name, count, MAX_LITERALS))++def wrap_items(items, indent=" ", width=104):"""Comma-separated items wrapped to a readable width, as Java array/argument contents."""lines, current = [], indent@@ -61,6 +94,7 @@ def wrap_items(items, indent=" ", width=104):def words_block(name, words, doc, sort=True):items = sorted(words) if sort else list(words)+ _check_budget(name, len(items))lines, current = [], " "for word in items:piece = quote(word) + ", "