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): twelve hook defects, and the measurement behind each fix
Adeshina Lasisie6571d8de0e9
diff --git a/.github/workflows/java.yml b/.github/workflows/java.ymlindex 4018d945..73712f8b 100644--- a/.github/workflows/java.yml+++ b/.github/workflows/java.yml@@ -156,18 +156,22 @@ jobs:- name: Tests that need no modelworking-directory: laya-javarun: ./gradlew --no-daemon test- # Measured locally: 812 registered, 798 RUN -- the floor counts what ran, so the 14- # checkpoint-backed cases this lane aborts are not in it. The margin is 4, the same shape- # as the 685/680 it replaces, and for the reason the `tokenizer` parity cell gives: a- # floor below the total minus the SMALLEST class does not bind that class. `AgentHooksTest`- # is 8 tests, so at the old 680 the whole of it could be deleted with this step still- # green. Verified both ways: with `AgentHooksTest` dropped 790 run and this exits 1; with- # `HooksTest` dropped 693 run and it exits 1.+ # Measured locally on Corretto 17: 831 registered, 817 RUN -- the floor counts what ran,+ # so the 14 checkpoint-backed cases this lane aborts are not in it. The margin is 4, the+ # same shape as the 812/798 it replaces, and for the reason the `tokenizer` parity cell+ # gives: a floor below the total minus the SMALLEST class does not bind that class.+ # `AgentHooksTest` is 8 tests, so a floor more than 8 below the total would let the whole+ # of it be deleted with this step still green. Verified by actually shrinking the suite:+ # with `AgentHooksTest` dropped 809 run and this exits 1; with `HooksTest` and its stubs+ # dropped 695 run and it exits 1.+ #+ # This floor and the jdk-matrix one differ by one ON PURPOSE -- see that lane for why a+ # shared number let a whole five-test class be deleted there.- name: Model-free suite was not vacuousif: ${{ !cancelled() }}run: >python laya-java/scripts/check_test_results.py- laya-java/laya-java/build/test-results/test --min-tests 794 --allow-aborted+ laya-java/laya-java/build/test-results/test --min-tests 813 --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@@ -322,11 +326,22 @@ jobs:# checkpoint-backed factories abort here, would forgive it. Measured: with the flag# dropped, Gradle exits 0 and the floor alone exits 0 on 488 tests, having run JDK 17 twice# and reported it as two JDKs. With `--require-passed` it exits 1.+ #+ # 814, not the build lane's 813, and the one is the point. This lane runs one test MORE+ # than that one -- `TestJvmVersionTest` is `@EnabledIfSystemProperty` and only enabled+ # here -- so 818 run against a shared floor of 813 would be a margin of 5, and the+ # smallest class this lane could lose whole is `PreTokenizerTablesTest` at exactly 5.+ # That is not hypothetical. Measured on the previous shared floor of 794, with the+ # smallest `hooks.json` section emptied and no per-section guard: the build lane ran 793+ # and exited 1 by exactly one test, and this lane ran 794 -- exactly ON the floor, so+ # `check_test_results` exited 0 and the vacuity was invisible in the one lane that had the+ # margin to hide it. The emptiness guard inside `HooksTest.section` is the real fix for+ # that case; this keeps the arithmetic from being what saved it.- name: Model-free suite was not vacuous, and ran on the right JVMif: ${{ !cancelled() }}run: >python laya-java/scripts/check_test_results.py- laya-java/laya-java/build/test-results/test --min-tests 794 --allow-aborted+ laya-java/laya-java/build/test-results/test --min-tests 814 --allow-aborted--require-passed TestJvmVersionTest- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2if: ${{ failure() }}diff --git a/laya-java/CHANGELOG.md b/laya-java/CHANGELOG.mdindex 54a360ff..1616f90d 100644--- a/laya-java/CHANGELOG.md+++ b/laya-java/CHANGELOG.md@@ -58,8 +58,42 @@ see [Installing](README.md#installing).it behind a lock when asked, and totals usage. `Agent.predict` and `Agent.predictBatch` runit; `Agent.predictLong` deliberately does not, for the reason under *Known limitations*.Everything above is recorded from the reference in `fixtures/hooks.json`, including what a- start hook sees, what `skip` does to inference, and what a throwing hook does under each- policy.+ start hook sees, what `skip` does to inference, what a throwing hook does under each policy,+ and how a deadline is spelled in the line an overrun reports.+- Three **deliberate divergences** inside `hooks`, each because a number or a name differed+ between the runtimes where the port claims they do not:+ - A hook that outran `timeout(Duration)` is **cut off from the call**. The deadline bounds the+ WAIT, not the hook and not the request — neither runtime can interrupt a thread that will not+ cooperate — so the abandoned thread is still holding the live, mutable `PredictContext` of a+ call that moved on without it. Measured over 60 calls whose start hook overran a 50 ms+ deadline by 30 ms and then assigned results: 60 of 60 late writes were accepted, and+ `ctx.usage` ended up describing a different answer from `ctx.results` in 60 of 60; in some+ runs the caller itself got the abandoned hook's answer. Every `PredictContext` mutator now+ throws `IllegalStateException` for a thread whose deadline has passed, and the same 60 calls+ disagree 0 times. The reference has the identical hazard and no cheap way to close it. It is+ a narrowing, not a proof: with the overrun cut to 1–5 ms, so that the write and the deadline+ collide, 2 to 17 of 60 late writes still landed. The context's mutable fields are `volatile`+ for the same reason — after `join` expires there is no happens-before edge to the caller.+ - `Hooks.Totals` counts in `long`. Summing per-state `int` usage into an `int` wraps silently —+ three results of 1,000,000,000 input tokens each totalled `-1294967296` — and a Python `int`+ cannot, so the port would have been the only one of the two lying to a metering hook about+ what a call cost.+ - `PredictContext` refuses a null `states` or `questions` **by name**, rather than letting its+ own defensive copy throw a bare `NullPointerException`. Before the hooks were wired in,+ `predictBatch(List.of(), null)` returned an empty list, because the empty-state+ short-circuit ran before anything looked at the questions; the reference refuses a non-dict+ `questions` for an empty batch as much as for any other, so that empty list was this port's+ divergence rather than a ported behaviour.+- The two lines dispatch reports are **greppable across both runtimes**, which they were not.+ A deadline is formatted as CPython's `%g` formats it, so a one-second deadline reads+ `exceeded 1s` and not `exceeded 1.0s` — a whole number of seconds being the common case for a+ deadline — with the rendering recorded per value in `fixtures/hooks.json` rather than typed+ out. And `Hooks.onPredictStart` / `onPredictEnd` return NAMED classes (`_StartAdapter`,+ `_EndAdapter`, the reference's own names), because `getSimpleName()` of the anonymous classes+ they used to return is the empty string: the two advertised low-friction hooks reported+ `laya: hook .on_predict_start failed`, naming nothing, in the one line a swallowed telemetry+ failure leaves. `Hooks.hookName` and `Hooks.seconds` are public so a caller's own `onFailure`+ sink can produce the same text.- `Agent.using(tokenizer, config, session, modelName)` and `Agent.modelName()`: the checkpointname a hook reads off `PredictContext.model()`. `Agent.open` takes it from the modeldirectory's own name, since `rl_agent_config.json` does not carry one.@@ -97,6 +131,18 @@ see [Installing](README.md#installing).- `-PtestJavaVersion` runs the tests on a different JDK from the one the classes are compiledfor, because the toolchain pins the compiler to 17 and a lane that merely installs another JDKtests the same thing twice.+- Three guards against a suite that is green because it tested nothing. A fixture section that+ emptied used to produce a `@TestFactory` with no tests in it, which JUnit does not fail, so+ `HooksTest.section` now refuses an empty or missing section and names it — the count floor+ alone was not enough, because with the smallest section emptied the `build` lane ran 793+ against a floor of 794 and caught it by exactly one test while the `jdk-matrix` lane, one test+ higher, landed exactly ON 794 and exited 0. The two lanes now carry floors one apart for that+ reason. A recorded value with no Java counterpart used to fall into the branch that asserts+ only about the reference, so a representable addition stopped testing Java silently; the+ timeout factory now fails on a value it has been told nothing about. And the process-wide+ default hooks are cleared after every test in the module by an auto-registered+ `DefaultHooksIsolation` extension, rather than by two classes remembering to — pinned by a+ class that deliberately does not remember.- That matrix earned itself on its first run. The JDK 21 cell failed where 17 and 24 passed,because `Character.isLetter` on Unicode 15.0 agrees with CPython 15.0 EXACTLY, and a test hadasserted that the JDK disagrees. Catching up is not a reason to drop the table -- it is thediff --git a/laya-java/README.md b/laya-java/README.mdindex 1495b71e..39cfd853 100644--- a/laya-java/README.md+++ b/laya-java/README.md@@ -384,11 +384,42 @@ per-call `HookCall`, hook objects before the `onStart`/`onEnd` callbacks. A tracwatch what a per-call hook did only sees it if it runs after it.`agent.hooks()` also carries the policy. `raiseErrors(false)` reports a throwing hook and carries-on, which is what a telemetry hook needs — it must not be able to fail a request.-`concurrent(false)` serialises hooks that are not re-entrant. `timeout(Duration)` bounds each hook-call; an overrunning hook fails the request, though it **keeps running** in the background, since-neither runtime can interrupt a thread that will not cooperate. A `HookCall` can override-`raiseErrors` and `timeout` for one call without touching the others.+on, which is what a telemetry hook needs — it must not be able to fail a request. An `Error` is+rethrown whatever it says, which is the reference's rule in Java terms: it catches `Exception` and+deliberately not `BaseException`. `concurrent(false)` serialises hooks that are not re-entrant.+A `HookCall` can override `raiseErrors` and `timeout` for one call without touching the others.++`timeout(Duration)` bounds **the wait** for each hook call — not the hook, and not the request. An+overrunning hook fails the call and **keeps running**, since neither runtime can interrupt a thread+that will not cooperate, so a hook that blocks forever leaks a daemon thread per call. That much is+the reference's behaviour.++Where this port diverges, deliberately: the abandoned thread is then **cut off from the call**.+Once its deadline has passed, every `ctx` mutator it calls throws `IllegalStateException` instead+of rewriting a call that moved on without it. The reference has the identical hazard and no cheap+way to close it. Measured here before the guard, over 60 calls whose start hook overran a 50 ms+deadline by 30 ms and then assigned results: 60 of 60 late writes were accepted, and `ctx.usage`+ended up describing a different answer from `ctx.results` in 60 of 60 — in some runs the *caller*+got the abandoned hook's answer. With the guard: 0 of 60. It is a narrowing and not a proof — a+write already past its check when the deadline expires still lands, which happened in 2 to 17 of+60 once the overrun was cut to 1–5 ms, so the window is a few instructions wide rather than the+whole remainder of the call.++Both lines dispatch reports — the swallowed failure and the overrun — name the hook as+`<class>.<event>` and spell a deadline in seconds exactly as the reference's `%g` does, so+`exceeded 1s` and not `exceeded 1.0s`, and one grep works against either runtime's logs.+`Hooks.onPredictStart`/`onPredictEnd` return the reference's own `_StartAdapter`/`_EndAdapter`+classes for the same reason: the name is what appears in that line, and an anonymous Java class+has none. `Hooks.hookName(hook)` and `Hooks.seconds(duration)` are public, so your own+`onFailure` sink can produce the same text.++Two smaller divergences, both for the same reason — a number or a name that differed between the+runtimes where the port claims they do not. `Hooks.Totals` counts in `long`, because summing+per-state `int` usage into an `int` wrapped silently (three results of a billion input tokens+totalled `-1294967296`), and a Python `int` cannot. And a `PredictContext` refuses a null `states`+or `questions` by name rather than letting the copy throw a bare `NullPointerException`; before+hooks were wired in, `predictBatch(List.of(), null)` returned an empty list, which the reference+does not do either.Scope hooks to a block with `try (var scope = agent.hooks().hooksInstalled(tracer)) { ... }`. Itremoves one copy of each hook it added — not every copy by identity, which would take one thediff --git a/laya-java/build.gradle.kts b/laya-java/build.gradle.ktsindex e0e7697d..57f05211 100644--- a/laya-java/build.gradle.kts+++ b/laya-java/build.gradle.kts@@ -83,6 +83,15 @@ subprojects {// answer actually exists.systemProperty("laya.test.expectedJavaVersion", want.toString())}+ // Process-wide default hooks are global mutable state with no automatic restore, so a+ // test that sets one and does not clear it fails whichever test runs next. Two classes+ // clear it in their own teardown and that was the whole protection -- discipline, not a+ // mechanism, and correct only until the third class forgets. Auto-detection registers+ // `DefaultHooksIsolation` (see that class) for classes that have not opted in, which is+ // precisely the class that would forget. It is global to this module's tests, so+ // `src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension` is+ // the one file that says what it turns on, and it holds exactly one entry.+ systemProperty("junit.jupiter.extensions.autodetection.enabled", "true")// Passed through rather than inherited silently, so a lane that forgets them is a lane// whose parity tests abort loudly instead of one that quietly tests less.//diff --git a/laya-java/fixtures/hooks.json b/laya-java/fixtures/hooks.jsonindex a874b341..80f12904 100644--- a/laya-java/fixtures/hooks.json+++ b/laya-java/fixtures/hooks.json@@ -770,72 +770,112 @@"input": "None","accepted": true,"value": null,+ "seconds": null,"error": null},{"input": "1","accepted": true,"value": 1.0,+ "seconds": "1",+ "error": null+ },+ {+ "input": "2",+ "accepted": true,+ "value": 2.0,+ "seconds": "2",+ "error": null+ },+ {+ "input": "10",+ "accepted": true,+ "value": 10.0,+ "seconds": "10",+ "error": null+ },+ {+ "input": "60",+ "accepted": true,+ "value": 60.0,+ "seconds": "60","error": null},{"input": "1.5","accepted": true,"value": 1.5,+ "seconds": "1.5","error": null},{"input": "0.05","accepted": true,"value": 0.05,+ "seconds": "0.05",+ "error": null+ },+ {+ "input": "1e-07",+ "accepted": true,+ "value": 1e-07,+ "seconds": "1e-07","error": null},{"input": "'0.5'","accepted": true,"value": 0.5,+ "seconds": "0.5","error": null},{"input": "0","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got 0"},{"input": "0.0","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got 0.0"},{"input": "-1","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got -1"},{"input": "-0.5","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got -0.5"},{"input": "nan","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got nan"},{"input": "inf","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got inf"},{"input": "-inf","accepted": false,"value": null,+ "seconds": null,"error": "hooks_timeout must be a positive finite number or None; got -inf"}],diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookCall.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookCall.javaindex b290cd99..0b56b3c5 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookCall.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookCall.java@@ -31,7 +31,11 @@ public record HookCall(List<Hook> hooks, List<Consumer<PredictContext>> onPredicnew HookCall(List.of(), List.of(), List.of(), null, null);public HookCall {- hooks = List.copyOf(hooks);+ // normalise, not List.copyOf: both copy and both refuse a null entry, but only one of+ // them says which argument was wrong. `List.copyOf` threw a bare NullPointerException+ // from inside the JDK, so "a hooks entry must not be null" was unreachable from `of` and+ // `andThen` -- the two ways a caller actually builds one of these.+ hooks = Hooks.normalise(hooks, null, null);onPredictStart = List.copyOf(onPredictStart);onPredictEnd = List.copyOf(onPredictEnd);timeout = Hooks.validateTimeout(timeout);@@ -49,7 +53,9 @@ public record HookCall(List<Hook> hooks, List<Consumer<PredictContext>> onPredic/** Several hooks, for this call only, in the given order. */public static HookCall of(List<? extends Hook> hooks) {- return new HookCall(List.copyOf(hooks), List.of(), List.of(), null, null);+ // Handed over unfiltered, so the canonical constructor above is what copies and what+ // refuses a null entry. `List.copyOf` here threw before it could.+ return new HookCall(new ArrayList<>(hooks), List.of(), List.of(), null, null);}/** This call with one more hook appended. */diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookRegistry.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookRegistry.javaindex 9ee8519c..5bd2eee6 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookRegistry.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/HookRegistry.java@@ -35,7 +35,8 @@ public final class HookRegistry {/** Installs one hook. Returns this, for chaining. */public HookRegistry addHook(Hook hook) {- return addHooks(List.of(hook));+ // Hooks.singleton, not List.of: see that method for why a null has to reach normalise.+ return addHooks(Hooks.singleton(hook));}/** Installs several hooks, in order. Returns this, for chaining. */@@ -121,10 +122,14 @@ public final class HookRegistry {** <p>The scan runs BACKWARDS, taking the most recent match, because installation* appends and a hook that was already there sits earlier than this scope's copy of it.- * That direction is fidelity to the reference and nothing more: the copies are the same- * object, so the list left behind is identical either way and no test can tell the two- * apart. Measured, not assumed — reversing the loop survives the whole suite. What IS- * observable, and is pinned, is that only ONE copy goes.+ * That is the reference's direction, and it is OBSERVABLE — an earlier version of this+ * paragraph claimed it was not, on the grounds that the copies are the same object. They+ * are, so the MULTISET left behind is identical either way; the ORDER is not, and order+ * is the one thing about a hook list that is a contract. With {@code addHook(a)},+ * {@code addHook(x)} and then {@code hooksInstalled(a)} the list is {@code [a, x, a]}:+ * dropping the last match leaves {@code [a, x]} and dropping the first leaves+ * {@code [x, a]}, so a forward scan would reorder two hooks the caller installed itself+ * and change which one sees the other's work. A test pins the direction.** <p>Idempotent, as {@link AutoCloseable} asks: closing twice would otherwise take a* second copy that belongs to someone else.diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/Hooks.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/Hooks.javaindex 68baa981..5b6858d6 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/Hooks.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/Hooks.java@@ -5,6 +5,7 @@ import com.convaiinnovations.laya.Question;import java.time.Duration;import java.util.ArrayList;import java.util.List;+import java.util.Locale;import java.util.Map;import java.util.concurrent.locks.Lock;import java.util.function.Consumer;@@ -91,8 +92,18 @@ public final class Hooks {* its budget dropped and which question was blamed. This is the sum over the call, which is* the only number a hook can report without re-deriving per-state attribution the reference* does not give it either.+ *+ * <p>{@code long}, not {@code int}, and that is a DELIBERATE DIVERGENCE from the reference's+ * shape rather than a transcription slip. A {@link com.convaiinnovations.laya.Usage} counts+ * one state in an {@code int}; summing those into an {@code int} wraps silently, and the+ * wrap was measured — three results of 1,000,000,000 input tokens each totalled+ * {@code -1294967296}. The reference cannot produce that number, because a Python+ * {@code int} does not overflow, so a port that reported it would be the only one of the two+ * runtimes lying to a metering hook about what a call cost. A {@code long} holds the sum of+ * {@link Integer#MAX_VALUE} over more than four billion results, which is past the point+ * where the batch itself is the problem.*/- public record Totals(int inputTokens, int outputTokens) {+ public record Totals(long inputTokens, long outputTokens) {}/**@@ -177,33 +188,69 @@ public final class Hooks {*/public static Hook onPredictStart(Consumer<PredictContext> callback) {requireCallback(callback, "onPredictStart");- return new Hook() {- @Override- public void onPredictStart(PredictContext ctx) {- callback.accept(ctx);- }-- @Override- public String toString() {- return "onPredictStart(" + callback + ")";- }- };+ return new _StartAdapter(callback);}/** Wraps a hook object around a plain {@code onPredictEnd} callback. */public static Hook onPredictEnd(Consumer<PredictContext> callback) {requireCallback(callback, "onPredictEnd");- return new Hook() {- @Override- public void onPredictEnd(PredictContext ctx) {- callback.accept(ctx);- }+ return new _EndAdapter(callback);+ }- @Override- public String toString() {- return "onPredictEnd(" + callback + ")";- }- };+ /**+ * The reference's {@code _StartAdapter}, name included.+ *+ * <p>A leading underscore is not a Java convention and this is the only place in the port+ * that uses one. It is here because the class name is DATA: {@link #dispatch} and+ * {@link #call} quote it in the two lines they report, the reference quotes+ * {@code type(hook).__name__} and {@code method.__qualname__} in the same two, and+ * {@link #call} promises a caller grepping their logs across the runtimes finds the same+ * text. These two adapters are the advertised low-friction way to add one callback, so they+ * are the hooks most likely to be the ones named in a failure line.+ *+ * <p>A NAMED class rather than the anonymous one this was: {@link Class#getSimpleName} of an+ * anonymous class is the EMPTY STRING, so both lines read {@code laya: hook .on_predict_start+ * exceeded 0.05s} — a blank where the reference puts {@code _StartAdapter.on_predict_start}.+ * The hook a {@code raiseErrors(false)} policy exists to protect is a telemetry hook, and it+ * could not be identified from its own failure line.+ */+ private static final class _StartAdapter implements Hook {++ private final Consumer<PredictContext> callback;++ _StartAdapter(Consumer<PredictContext> callback) {+ this.callback = callback;+ }++ @Override+ public void onPredictStart(PredictContext ctx) {+ callback.accept(ctx);+ }++ @Override+ public String toString() {+ return "onPredictStart(" + callback + ")";+ }+ }++ /** The reference's {@code _EndAdapter}, name included — see {@link _StartAdapter}. */+ private static final class _EndAdapter implements Hook {++ private final Consumer<PredictContext> callback;++ _EndAdapter(Consumer<PredictContext> callback) {+ this.callback = callback;+ }++ @Override+ public void onPredictEnd(PredictContext ctx) {+ callback.accept(ctx);+ }++ @Override+ public String toString() {+ return "onPredictEnd(" + callback + ")";+ }}private static void requireCallback(Consumer<PredictContext> callback, String name) {@@ -293,9 +340,17 @@ public final class Hooks {}}- /** Appends one hook to the process-wide defaults. */+ /**+ * Appends one hook to the process-wide defaults.+ *+ * <p>Process-wide and mutable, with no automatic restore: whatever is set here applies to+ * every agent in the JVM until something clears it. A test that sets a default and does not+ * clear it in teardown pollutes every test that runs after it, and the pollution surfaces as+ * a failure somewhere else. {@link #clearDefaultHooks} in an {@code @AfterEach} is the whole+ * discipline, and this port's own suites do exactly that.+ */public static void addDefaultHook(Hook hook) {- List<Hook> normalised = normalise(List.of(hook), null, null);+ List<Hook> normalised = normalise(singleton(hook), null, null);synchronized (DEFAULTS_MUTEX) {List<Hook> grown = new ArrayList<>(defaults);grown.addAll(normalised);@@ -303,6 +358,21 @@ public final class Hooks {}}+ /**+ * A one-element list that tolerates null, so {@link #normalise} is what refuses it.+ *+ * <p>{@code List.of(hook)} would throw a bare {@link NullPointerException} from inside the+ * JDK first, which made the "a hooks entry must not be null" message unreachable from every+ * single-hook entry point — {@link #addDefaultHook}, {@link HookRegistry#addHook} and+ * {@link HookCall#andThen} — and handed the caller a stack trace naming neither the argument+ * nor what was wrong with it.+ */+ static List<Hook> singleton(Hook hook) {+ List<Hook> one = new ArrayList<>(1);+ one.add(hook);+ return one;+ }+/** Removes every process-wide default hook. */public static void clearDefaultHooks() {synchronized (DEFAULTS_MUTEX) {@@ -323,16 +393,32 @@ public final class Hooks {* {@code -Werror} needs {@code @SuppressWarnings("try")} on the enclosing method. That is a* known javac wart about the idiom, not about this method.*+ * <p>The scopes NEST. Closing one restores the value it found, not {@code false}, so an+ * inner scope closing does not switch the defaults back on inside an outer one that is still+ * open. That is the reference's {@code _SKIP_DEFAULTS.reset(token)}, which nests by+ * construction; a {@link ThreadLocal} has no token, so the captured value is the token.+ ** <p>This is the reference's {@code _SKIP_DEFAULTS}, which a router enters so that a scan* made of many internal predictions fires a process-wide hook once for the scan rather than* once per forward pass. There it is a {@code contextvars.ContextVar} and here it is a* {@link ThreadLocal}, and the difference is real: a {@code ContextVar} is copied into an* asyncio task, while a {@code ThreadLocal} is not inherited by a thread the scope starts.- * Work handed to another thread inside the scope therefore sees the defaults again. Nothing- * in this port dispatches hooks off the calling thread, so there is nowhere for that to bite- * today — it is written down because the first code that does will be surprised otherwise.+ * Work handed to another thread inside the scope therefore sees the defaults again.+ *+ * <p>One place in this port DOES run a hook off the calling thread — {@link Policy#timeout}+ * runs each hook on a {@code laya-hook-timeout} thread so the wait can be bounded — and an+ * earlier version of this paragraph said there was no such place. It still does not bite,+ * but for a different reason than "there is nowhere for it to": this flag is read by+ * {@link #compose}, on the calling thread, before anything is dispatched, so the hook thread+ * never consults it. The reference copies the whole context into its runner thread+ * ({@code contextvars.copy_context()}) rather than relying on that, which is why a+ * {@code ContextVar} a CALLER set is visible to a hook there and a {@link ThreadLocal} one+ * is not visible here. That difference is real and unported.*/public static DefaultsScope withoutDefaultHooks() {+ // The PREVIOUS value, not false: the scopes nest, and an inner one closing must not+ // cancel an outer one's suppression. This is the reference's `_SKIP_DEFAULTS.reset(token)`+ // written out -- a ThreadLocal has no token, so the token is the captured value.boolean previous = SKIP_DEFAULTS.get();SKIP_DEFAULTS.set(true);return () -> SKIP_DEFAULTS.set(previous);@@ -382,8 +468,10 @@ public final class Hooks {* the Java side has to produce the same number from the representable equivalent.*/public static Totals aggregateUsage(List<Prediction> results) {- int input = 0;- int output = 0;+ // Summed as longs: see Totals for the measured wrap an int accumulator produced, and for+ // why reproducing it would be fidelity to a shape rather than to a behaviour.+ long input = 0;+ long output = 0;for (Prediction result : results) {input += result.usage().inputTokens();output += result.usage().outputTokens();@@ -400,9 +488,23 @@ public final class Hooks {* when {@code raiseErrors} is false.** <p>A timed-out hook KEEPS RUNNING. Neither Java nor Python can interrupt a thread that- * will not cooperate, so the deadline protects the request and not the process — a hook that- * blocks forever leaks a thread per call. That is the reference's behaviour too, and it is- * the reason the timeout is opt-in.+ * will not cooperate, so what the deadline bounds is THE WAIT — not the request, and not the+ * process. The distinction is not pedantry and an earlier version of this paragraph had it+ * wrong. The abandoned thread still holds the live, mutable {@link PredictContext} of a call+ * that has moved on without it, and it can still write to it: measured over 60 identical+ * calls with a hook that overran a 50 ms deadline and then assigned results, the late+ * write was accepted 60 times out of 60 and {@code ctx.usage} ended up describing a+ * different answer from {@code ctx.results} in 60 of them — because {@link #around} had+ * already totalled the usage of the answer it saw. In the runs where the write landed inside+ * the handful of microseconds before {@code around} read the results back, the CALLER was+ * handed the abandoned hook's answer instead. That is the reference's hazard too — it has+ * the same abandoned thread and the same shared dataclass.+ *+ * <p>What this port does about it, and the reference cannot easily: the thread is MARKED as+ * abandoned the moment its deadline expires, and {@link PredictContext} refuses a write from+ * a thread that carries that mark: the same 60 calls then disagree 0 times. See+ * {@link PredictContext#states(List)} for the one window it does not close. A hook that+ * blocks forever still leaks a thread per call, which is why the timeout is opt-in.** <p>{@code raiseErrors} governs a {@link RuntimeException} and nothing else. An* {@link Error} is rethrown whatever the policy says, which is the reference's rule in Java@@ -430,7 +532,7 @@ public final class Hooks {throw problem;}policy.onFailure().accept(String.format("laya: hook %s.%s failed: %s",- hook.getClass().getSimpleName(), event.wireName(), problem.getMessage()));+ hookName(hook), event.wireName(), problem.getMessage()));}}}@@ -453,17 +555,23 @@ public final class Hooks {try {runner.join(timeout.toMillis(), timeout.toNanosPart() % 1_000_000);} catch (InterruptedException interrupted) {+ // Re-asserted BEFORE wrapping, because catching InterruptedException clears the+ // flag: a caller up the stack that polls `Thread.interrupted()` to decide whether to+ // shut down would otherwise be told it was never asked to.Thread.currentThread().interrupt();throw new IllegalStateException("interrupted while waiting for hook "- + hook.getClass().getSimpleName() + "." + event.wireName(), interrupted);+ + hookName(hook) + "." + event.wireName(), interrupted);}if (runner.isAlive()) {+ // The thread is not coming back under our control, so it is cut off from the call+ // instead: anything it writes to the context from here on is refused. See dispatch.+ ctx.abandon(runner);// Seconds, not `Duration.toString`'s "PT0.05S". The reference names the hook as// `<class>.<method>` and the deadline in seconds, and a caller grepping their logs- // across the two runtimes should find the same line.+ // across the two runtimes should find the same line -- which is what `hookName` and+ // `seconds` are for, and what each of them documents it used to get wrong.throw new HookTimeoutException(String.format("laya: hook %s.%s exceeded %ss",- hook.getClass().getSimpleName(), event.wireName(),- timeout.toNanos() / 1e9));+ hookName(hook), event.wireName(), seconds(timeout)));}if (box[0] instanceof RuntimeException problem) {throw problem;@@ -473,6 +581,84 @@ public final class Hooks {}}+ /**+ * The name the two reported lines call a hook, which is the reference's own choice of name.+ *+ * <p>{@link Class#getSimpleName} alone is not it. For an ANONYMOUS class it is the empty+ * string, so {@code "laya: hook %s.%s failed"} came out as {@code laya: hook .on_predict_start+ * failed} — the one line a swallowed telemetry failure produces, naming nothing. Python has+ * no anonymous class and its {@code __qualname__} always names something, so the reference+ * cannot reach this case at all. A local or anonymous class falls back to the binary name's+ * last segment, {@code Enclosing$1}, which is ugly and is still a name.+ *+ * <p>Public because {@link Policy#onFailure} is a caller's own sink: a sink that wants to+ * attribute a failure to a hook should not have to re-derive the name this port already+ * picked, and get a blank for an anonymous one.+ */+ public static String hookName(Hook hook) {+ Class<?> type = hook.getClass();+ String simple = type.getSimpleName();+ if (!simple.isEmpty()) {+ return simple;+ }+ String binary = type.getName();+ int lastDot = binary.lastIndexOf('.');+ return lastDot < 0 ? binary : binary.substring(lastDot + 1);+ }++ /**+ * A deadline in seconds, formatted as the reference's {@code %g} formats it.+ *+ * <p>Not {@code %s} on a {@code double}, which is what this was: that prints {@code 1.0} for+ * a one-second deadline where CPython's {@code %g} prints {@code 1}, so the one line the+ * javadoc on {@link #call} promises would be greppable across both runtimes differed on the+ * commonest value there is. Measured in both: {@code 'laya: hook X exceeded %gs' % 1} is+ * {@code exceeded 1s}, and {@code String.format("exceeded %ss", 1.0)} is+ * {@code exceeded 1.0s}.+ *+ * <p>Java's own {@code %g} is not C's and cannot be used: it neither strips trailing zeros+ * nor switches to a fixed-point form, so it renders a one-second deadline as+ * {@code 1.00000}. This is C's rule written out — six significant digits, the exponent form+ * outside {@code [1e-4, 1e6)}, trailing zeros removed. {@code fixtures/hooks.json} records+ * CPython's own rendering per recorded deadline — {@code 1}, {@code 2}, {@code 10},+ * {@code 60}, {@code 1.5}, {@code 0.05} and {@code 1e-07} — and a test compares this method+ * against that field rather than against a string somebody typed. Checked by hand over a+ * wider sweep as well: 23 values including {@code 0.1}, {@code 0.25}, {@code 3600},+ * {@code 86400}, {@code 123456.789} and {@code 1e-09}, byte-identical on all 23.+ *+ * <p>Public for the same reason as {@link #hookName}: a caller logging a deadline of their+ * own should be able to produce the line this port produces, rather than one that differs+ * from it in the same way it used to differ from the reference.+ */+ public static String seconds(Duration timeout) {+ double value = timeout.toNanos() / 1e9;+ // %.5e is six significant digits, and its exponent is the one AFTER rounding -- which is+ // what the branch below has to read, or 9.999999 lands in the wrong form.+ String scientific = String.format(Locale.ROOT, "%.5e", value);+ int marker = scientific.indexOf('e');+ int exponent = Integer.parseInt(scientific.substring(marker + 1));+ if (exponent < -4 || exponent >= 6) {+ return trimZeros(scientific.substring(0, marker))+ + String.format(Locale.ROOT, "e%s%02d", exponent < 0 ? "-" : "+",+ Math.abs(exponent));+ }+ return trimZeros(String.format(Locale.ROOT, "%." + (5 - exponent) + "f", value));+ }++ private static String trimZeros(String decimal) {+ if (decimal.indexOf('.') < 0) {+ return decimal;+ }+ int end = decimal.length();+ while (end > 0 && decimal.charAt(end - 1) == '0') {+ end--;+ }+ if (end > 0 && decimal.charAt(end - 1) == '.') {+ end--;+ }+ return decimal.substring(0, end);+ }+/** A hook that outran {@link Policy#timeout}. Unchecked, so the usual policy governs it. */public static final class HookTimeoutException extends RuntimeException {diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/PredictContext.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/PredictContext.javaindex 404657ca..a198c6fd 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/PredictContext.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/PredictContext.java@@ -7,7 +7,9 @@ import java.util.ArrayList;import java.util.LinkedHashMap;import java.util.List;import java.util.Map;+import java.util.Set;import java.util.UUID;+import java.util.concurrent.ConcurrentHashMap;/*** One call, as every hook of that call sees it — and as a hook may change it.@@ -23,7 +25,10 @@ import java.util.UUID;* sit in a set keyed by the call rather than by its contents, which is what a Java object does* by default — so there is no {@code equals} or {@code hashCode} here, on purpose.*- * <p>Not thread-safe, and not meant to be: hooks run on the calling thread, in order.+ * <p>Not thread-safe, and not meant to be: hooks run on the calling thread, in order. The one+ * exception is the thread a {@link Hooks.Policy#timeout} runs a hook on, which keeps running+ * after its deadline expires while the call moves on without it — see {@link #states(List)} for+ * what this class does about that and what it cannot do.** <p>Two of the reference's fields are absent. {@code router} and {@code decision} carry a* {@code RouteDecision} to an {@code on_route} hook, and nothing in this port dispatches that@@ -39,25 +44,61 @@ public final class PredictContext {private final String model;private final Predictor predictor;- private List<Object> states;- private Map<String, Question> questions;- private List<Prediction> results;- private Integer maxLen;- private Integer headMaxLen;- private Hooks.Totals usage;- private Double elapsedMs;- private Throwable error;+ // Volatile, every one of them. A hook that overran its deadline keeps running on another+ // thread, and after `Thread.join` times out there is no happens-before edge between that+ // thread's writes and the calling thread's reads -- so a plain field could hand the caller a+ // torn view, or a stale one indefinitely. Volatile does not make the call CORRECT under a+ // late writer, which is what `abandoned` below is for; it makes what the reader sees be a+ // value somebody actually wrote.+ private volatile List<Object> states;+ private volatile Map<String, Question> questions;+ private volatile List<Prediction> results;+ private volatile Integer maxLen;+ private volatile Integer headMaxLen;+ private volatile Hooks.Totals usage;+ private volatile Double elapsedMs;+ private volatile Throwable error;++ /**+ * Threads whose deadline expired, and whose writes are therefore refused.+ *+ * <p>Empty for every call that does not use {@link Hooks.Policy#timeout}, and at most one+ * entry per overrun. A set rather than a flag because a chain can overrun more than once.+ */+ private final Set<Thread> abandoned = ConcurrentHashMap.newKeySet();/*** A context for one call.*+ * <p>Neither {@code states} nor {@code questions} may be null, and each is refused by NAME.+ * A context copies both at construction — it owns what every hook of the call then edits —+ * so a null cannot be carried through to be refused later, the way the reference's plain+ * dataclass carries it to its own {@code "questions must be a dict of question id ->+ * definition"} check. The refusal is the same refusal, moved to where this port can make it.+ *+ * <p>This is a deliberate behaviour change, and it is worth naming because it is small and+ * invisible: before the hooks were wired in, {@code predictBatch(List.of(), null)} returned+ * an empty list, because the empty-state short-circuit ran before anything looked at the+ * questions. It now throws. The alternative — tolerating a null and treating it as "no+ * questions" — would make {@code predictBatch(states, null)} answer a real batch with empty+ * answers and zero usage instead of refusing it, which is the failure mode a typed API+ * exists to prevent. The reference refuses it too, for empty states as much as for any+ * other; returning a list there was this port's own divergence, not a ported behaviour.+ ** @param model the resolved checkpoint name, or null when the caller named none* @param predictor the agent or router answering this call, or null* @param maxLen a per-call token budget, or null for the checkpoint's own* @param headMaxLen a per-call head budget, or null for the checkpoint's own+ * @throws IllegalArgumentException for a null {@code states} or {@code questions}*/public PredictContext(List<?> states, Map<String, Question> questions, String model,Predictor predictor, Integer maxLen, Integer headMaxLen) {+ if (states == null) {+ throw new IllegalArgumentException("states must not be null");+ }+ if (questions == null) {+ throw new IllegalArgumentException("questions must not be null");+ }this.states = new ArrayList<>(states);this.questions = new LinkedHashMap<>(questions);this.model = model;@@ -92,8 +133,34 @@ public final class PredictContext {return states;}- /** Replaces the states. Inference is handed what the LAST start hook left here. */+ /**+ * Replaces the states. Inference is handed what the LAST start hook left here.+ *+ * <p>Refused from a thread whose {@link Hooks.Policy#timeout} already expired, and so is+ * every other mutator here. This is a DELIBERATE DIVERGENCE from the reference, which has no+ * equivalent and cannot cheaply get one.+ *+ * <p>Why it exists: a hook that overruns its deadline is abandoned, not stopped — neither+ * runtime can interrupt a thread that will not cooperate — and it is still holding this+ * object while the call carries on without it. Measured on this port before the guard, over+ * 60 calls whose start hook overran a 50 ms deadline by 30 ms and then assigned+ * results: 60 of 60 late writes were accepted, and {@code usage} then described a different+ * answer from {@code results} in 60 of 60, because {@link Hooks#around} had already totalled+ * the usage of the answer it saw. With the guard, the same 60 calls refuse 60 of 60 and+ * disagree 0 times. The reference has the identical hazard, so this is the port being+ * stricter rather than the port being different for its own sake.+ *+ * <p>What it does NOT fix: a write already PAST this check when the deadline expires still+ * lands. Measured on the same harness with the overrun cut to 1–5 ms, so that the write+ * and the deadline collide: 2 to 17 of 60 late writes were still accepted. The window shrinks+ * from "the whole remainder of the call" to "the few instructions between the check and the+ * store", which is a narrowing, not a proof — and the guard is cheap enough to be worth the+ * narrowing on its own.+ *+ * @throws IllegalStateException when the calling thread's deadline has already expired+ */public void states(List<?> replacement) {+ refuseIfAbandoned("states");this.states = new ArrayList<>(replacement);}@@ -102,8 +169,14 @@ public final class PredictContext {return questions;}- /** Replaces the questions, keeping the given iteration order — a choice's options are positional. */+ /**+ * Replaces the questions, keeping the given iteration order — a choice's options are positional.+ *+ * @throws IllegalStateException when the calling thread's deadline has already expired; see+ * {@link #states(List)}+ */public void questions(Map<String, Question> replacement) {+ refuseIfAbandoned("questions");this.questions = new LinkedHashMap<>(replacement);}@@ -119,8 +192,14 @@ public final class PredictContext {return results;}- /** Replaces the results. From an end hook this is what the caller receives. */+ /**+ * Replaces the results. From an end hook this is what the caller receives.+ *+ * @throws IllegalStateException when the calling thread's deadline has already expired; see+ * {@link #states(List)}+ */public void results(List<Prediction> replacement) {+ refuseIfAbandoned("results");this.results = replacement;}@@ -129,8 +208,14 @@ public final class PredictContext {return maxLen;}- /** Overrides the token budget for this call. */+ /**+ * Overrides the token budget for this call.+ *+ * @throws IllegalStateException when the calling thread's deadline has already expired; see+ * {@link #states(List)}+ */public void maxLen(Integer replacement) {+ refuseIfAbandoned("maxLen");this.maxLen = replacement;}@@ -139,8 +224,14 @@ public final class PredictContext {return headMaxLen;}- /** Overrides the head budget for this call. */+ /**+ * Overrides the head budget for this call.+ *+ * @throws IllegalStateException when the calling thread's deadline has already expired; see+ * {@link #states(List)}+ */public void headMaxLen(Integer replacement) {+ refuseIfAbandoned("headMaxLen");this.headMaxLen = replacement;}@@ -197,8 +288,11 @@ public final class PredictContext {* "nothing", and an empty call has nothing to answer.** @throws IllegalArgumentException when the count is neither 1 nor one per state+ * @throws IllegalStateException when the calling thread's deadline has already expired; see+ * {@link #states(List)}*/public void skip(List<Prediction> results) {+ refuseIfAbandoned("skip");if (results.size() != 1 && results.size() != states.size()) {throw new IllegalArgumentException(String.format("ctx.skip() takes one result for the whole call or one per state in "@@ -207,6 +301,25 @@ public final class PredictContext {this.results = results;}+ /**+ * Cuts {@code runner} off from this call: nothing it writes from here on is accepted.+ *+ * <p>Called by {@link Hooks} the moment a hook's deadline expires, which is the moment the+ * call stops being able to wait for it. See {@link #states(List)}.+ */+ void abandon(Thread runner) {+ abandoned.add(runner);+ }++ private void refuseIfAbandoned(String what) {+ if (!abandoned.isEmpty() && abandoned.contains(Thread.currentThread())) {+ throw new IllegalStateException(String.format(+ "laya: hook thread %s exceeded its deadline and was abandoned; this call has "+ + "moved on, so ctx.%s() is refused rather than applied to it",+ Thread.currentThread().getName(), what));+ }+ }+@Overridepublic String toString() {return "PredictContext[runId=" + runId + ", states=" + states.size()diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolation.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolation.javanew file mode 100644index 00000000..ae8daeb9--- /dev/null+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolation.java@@ -0,0 +1,36 @@+package com.convaiinnovations.laya;++import com.convaiinnovations.laya.hooks.Hooks;+import org.junit.jupiter.api.extension.AfterEachCallback;+import org.junit.jupiter.api.extension.Extension;+import org.junit.jupiter.api.extension.ExtensionContext;++/**+ * Clears the process-wide default hooks after EVERY test in this module.+ *+ * <p>{@link Hooks#setDefaultHooks} is process-wide, mutable and has no automatic restore: what+ * one test sets applies to every agent in the JVM until something clears it, and the pollution+ * surfaces as a failure in whichever test happens to run next. The global itself is properly+ * guarded — {@code Hooks} holds a mutex over it — so this is not a race; it is the ordinary+ * hazard of global state, and nothing about it is visible from the test that pays for it.+ *+ * <p>Two test classes already clear it in their own {@code @AfterEach}, and they still do. That+ * was the whole protection, and it was DISCIPLINE: correct today, and correct only until the+ * third class that touches the defaults forgets. This makes it structural instead. The two local+ * teardowns are deliberately kept rather than deleted, so that a class keeps its isolation even+ * if the registration below is ever switched off.+ *+ * <p>Registered by SERVICE LOADER, through+ * {@code src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension} and the+ * {@code junit.jupiter.extensions.autodetection.enabled} property the build sets — which is what+ * makes it apply to classes that have not opted in, and therefore to the class that forgets.+ * That property is global to this module's tests, so the service file is the one place to look+ * for what it turns on, and this is the only entry in it.+ */+public final class DefaultHooksIsolation implements Extension, AfterEachCallback {++ @Override+ public void afterEach(ExtensionContext context) {+ Hooks.clearDefaultHooks();+ }+}diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolationTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolationTest.javanew file mode 100644index 00000000..a4998d6a--- /dev/null+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/DefaultHooksIsolationTest.java@@ -0,0 +1,56 @@+package com.convaiinnovations.laya;++import static org.junit.jupiter.api.Assertions.assertEquals;++import com.convaiinnovations.laya.hooks.Hook;+import com.convaiinnovations.laya.hooks.Hooks;+import com.convaiinnovations.laya.hooks.PredictContext;+import java.util.List;+import org.junit.jupiter.api.DisplayName;+import org.junit.jupiter.api.MethodOrderer;+import org.junit.jupiter.api.Order;+import org.junit.jupiter.api.Test;+import org.junit.jupiter.api.TestMethodOrder;++/**+ * That {@link DefaultHooksIsolation} is actually registered, from a class that opts into nothing.+ *+ * <p>This class deliberately has NO {@code @AfterEach} and no {@code @ExtendWith}: it is the+ * class that forgot, which is the only case the extension exists for. The first test leaves a+ * process-wide default hook installed on purpose; the second asserts it is gone. Ordered,+ * because "the next test" is the whole claim and JUnit's default method order is deterministic+ * but not specified.+ *+ * <p>Without the service-loader registration — or without the+ * {@code junit.jupiter.extensions.autodetection.enabled} property the build sets — the second+ * test fails, which is what makes the mechanism a mechanism rather than a comment.+ */+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)+final class DefaultHooksIsolationTest {++ private static final Hook LEAK = new Hook() {+ @Override+ public void onPredictStart(PredictContext ctx) {+ // Never dispatched; this hook exists to be left behind.+ }+ };++ @Test+ @Order(1)+ @DisplayName("a test that installs a process-wide default and does not clean up after itself")+ void leavesADefaultInstalled() {+ Hooks.addDefaultHook(LEAK);+ assertEquals(List.of(LEAK), Hooks.defaultHooks(), "the default really was installed");+ }++ @Test+ @Order(2)+ @DisplayName("...does not take the next test with it")+ void theNextTestStartsClean() {+ assertEquals(List.of(), Hooks.defaultHooks(),+ "the previous test left a process-wide default hook installed and nothing in "+ + "this class clears it, so DefaultHooksIsolation is not registered -- every "+ + "test in the module after one that forgets is now running with a hook it "+ + "never asked for");+ }+}diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/HooksTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/HooksTest.javaindex 1485e3e4..c524b678 100644--- a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/HooksTest.java+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/HooksTest.java@@ -7,6 +7,7 @@ import static org.junit.jupiter.api.Assertions.assertNull;import static org.junit.jupiter.api.Assertions.assertSame;import static org.junit.jupiter.api.Assertions.assertThrows;import static org.junit.jupiter.api.Assertions.assertTrue;+import static org.junit.jupiter.api.Assertions.fail;import static org.junit.jupiter.api.DynamicTest.dynamicTest;import com.convaiinnovations.laya.hooks.Hook;@@ -19,8 +20,12 @@ import java.util.ArrayList;import java.util.LinkedHashMap;import java.util.List;import java.util.Map;+import java.util.concurrent.CountDownLatch;+import java.util.concurrent.TimeUnit;import java.util.concurrent.atomic.AtomicInteger;+import java.util.concurrent.atomic.AtomicReference;import java.util.function.Consumer;+import org.junit.jupiter.api.AfterAll;import org.junit.jupiter.api.AfterEach;import org.junit.jupiter.api.DisplayName;import org.junit.jupiter.api.DynamicTest;@@ -64,9 +69,33 @@ final class HooksTest {return (Map<String, Object>) (Map<?, ?>) Fixtures.load("hooks.json");}+ /**+ * One recorded section, which may never be EMPTY.+ *+ * <p>JUnit does not fail a {@code @TestFactory} that returns no tests, so a section that+ * emptied — a renamed key, a generator branch that stopped recording, a bad merge — produced+ * a factory with nothing in it and a green suite.+ *+ * <p>The count floor in CI is the other half of that guard and it is not enough on its own.+ * Measured with this check deleted and {@code as_sequence} — 5 cases, the smallest section —+ * emptied: Gradle still exits 0, 812 of 831 tests run, and the floor that was in place when+ * the section was last recorded, 794, does not notice at all. A floor only ever notices+ * because it sits within a few tests of the total, which makes WHICH lane it is in decide+ * whether it notices: the {@code build} lane catches that emptying by one test, and a floor+ * shared with {@code jdk-matrix}, which runs one test more because+ * {@code TestJvmVersionTest} is enabled only there, would have landed exactly ON it and+ * exited 0. The two lanes now carry floors one apart for that reason, and this check is the+ * per-section half that does not depend on the arithmetic at all. It names the section.+ */@SuppressWarnings("unchecked")private static List<Object> section(String name) {- return (List<Object>) family().get(name);+ Object recorded = family().get(name);+ assertNotNull(recorded, "hooks.json has no section called " + name+ + "; this factory would otherwise register no tests at all");+ List<Object> cases = (List<Object>) recorded;+ assertFalse(cases.isEmpty(), "hooks.json section " + name + " is EMPTY, so the factory "+ + "reading it registers no tests -- which JUnit does not treat as a failure");+ return cases;}@SuppressWarnings("unchecked")@@ -461,14 +490,28 @@ final class HooksTest {// -- validate_timeout ---------------------------------------------------@TestFactory- @DisplayName("a timeout is a positive duration, and the non-positive ones are refused")+ @DisplayName("a timeout is a positive duration, is refused when non-positive, and renders as the reference renders it")List<DynamicTest> timeoutsMatch() {List<DynamicTest> tests = new ArrayList<>();for (Object raw : section("timeouts")) {Map<String, Object> one = map(raw);String input = (String) one.get("input");- Duration candidate = durationFor(input);- if (candidate == null && !"None".equals(input)) {+ if (!DURATIONS.containsKey(input)) {+ if (!UNREPRESENTABLE.contains(input)) {+ // A value was added to the reference's HOOK_TIMEOUT_VALUES and nobody said+ // which of the two it is. It MUST NOT fall through to the unrepresentable+ // branch by default, because that branch asserts only about the Python side+ // and never calls validateTimeout at all -- so a representable addition+ // would quietly stop testing Java. Measured: appending a plain `2` to+ // HOOK_TIMEOUT_VALUES survived the whole suite before this guard existed.+ tests.add(dynamicTest(input + " (UNRECORDED)", () ->+ fail("hooks.json records the timeout value " + input + ", which this "+ + "factory maps to neither a Duration nor the unrepresentable "+ + "set. Add it to DURATIONS, or to UNREPRESENTABLE with the "+ + "reason -- leaving it out stops the Java side being tested "+ + "for it.")));+ continue;+ }// nan, inf and -inf have no Duration, and '0.5' is a string the reference// coerces where Java has no such value to be handed. Unreachable, not skipped:// the refusal is still asserted on the reference's side.@@ -481,9 +524,19 @@ final class HooksTest {}));continue;}+ Duration candidate = DURATIONS.get(input);tests.add(dynamicTest(input, () -> {if (Boolean.TRUE.equals(one.get("accepted"))) {assertEquals(candidate, Hooks.validateTimeout(candidate));+ if (candidate != null) {+ // The deadline as the overrun line spells it. `%g`, recorded from+ // CPython, is `1` for a one-second deadline where `%s` on a double is+ // `1.0` -- and a whole number of seconds is the commonest deadline there+ // is, so it is the commonest form of that line.+ assertEquals(one.get("seconds"), Hooks.seconds(candidate),+ "the deadline in the overrun message, as the reference formats "+ + "it with %g");+ }} else {assertThrows(IllegalArgumentException.class,() -> Hooks.validateTimeout(candidate));@@ -493,19 +546,37 @@ final class HooksTest {return tests;}- private static Duration durationFor(String recorded) {- return switch (recorded) {- case "None" -> null;- case "1" -> Duration.ofSeconds(1);- case "1.5" -> Duration.ofMillis(1500);- case "0.05" -> Duration.ofMillis(50);- case "0", "0.0" -> Duration.ZERO;- case "-1" -> Duration.ofSeconds(-1);- case "-0.5" -> Duration.ofMillis(-500);- default -> null;- };+ /**+ * Every recorded timeout value that HAS a {@link Duration}, including null for "no limit".+ *+ * <p>A map with an explicit null value rather than a {@code switch} returning null on its+ * default arm: the default arm made "unmapped" and "representable as no limit" the same+ * answer, which is how a representable addition could slip into the branch that tests+ * nothing. {@code containsKey} tells them apart.+ */+ private static final Map<String, Duration> DURATIONS = durations();++ private static Map<String, Duration> durations() {+ Map<String, Duration> out = new LinkedHashMap<>();+ out.put("None", null);+ out.put("1", Duration.ofSeconds(1));+ out.put("2", Duration.ofSeconds(2));+ out.put("10", Duration.ofSeconds(10));+ out.put("60", Duration.ofSeconds(60));+ out.put("1.5", Duration.ofMillis(1500));+ out.put("0.05", Duration.ofMillis(50));+ out.put("1e-07", Duration.ofNanos(100));+ out.put("0", Duration.ZERO);+ out.put("0.0", Duration.ZERO);+ out.put("-1", Duration.ofSeconds(-1));+ out.put("-0.5", Duration.ofMillis(-500));+ return out;}+ /** The recorded values a {@link Duration} cannot hold at all, each for a stated reason. */+ private static final List<String> UNREPRESENTABLE =+ List.of("'0.5'", "nan", "inf", "-inf");+// -- the registry -------------------------------------------------------@TestFactory@@ -757,8 +828,14 @@ final class HooksTest {return null;}Map<String, Object> want = map(recorded);- return Map.of("input_tokens", integer(want.get("input_tokens")),- "output_tokens", integer(want.get("output_tokens")));+ // Long, because Hooks.Totals counts in longs -- see that record for the measured int+ // overflow. A recorded Integer would never equal what a hook actually read.+ return Map.of("input_tokens", longOf(want.get("input_tokens")),+ "output_tokens", longOf(want.get("output_tokens")));+ }++ private static Long longOf(Object value) {+ return value == null ? null : ((Number) value).longValue();}// -- the parts the reference cannot record ------------------------------@@ -767,8 +844,14 @@ final class HooksTest {@DisplayName("a hook that overruns its deadline fails the call rather than holding it")void aSlowHookTimesOut() {List<Object> log = new ArrayList<>();+ // One second, not five. The thread this test abandons cannot be joined -- that is the+ // behaviour being asserted -- so the only thing that bounds it is how long the hook+ // sleeps, and the suite should not carry a thread for five seconds to prove a 50 ms+ // deadline. A 20x margin over the deadline is still not a race: `join(50)` returns at+ // 50 ms whatever the hook is doing. `noAbandonedHookThreadOutlivesTheSuite` below is+ // what makes the bound an assertion rather than an intention.Hook slow = HookStubs.hook(log, "slow", HookStubs.Hooks0.EVENTS,- Map.of("on_predict_start", "sleep:5"), false);+ Map.of("on_predict_start", "sleep:1"), false);PredictContext ctx = new PredictContext(List.of("s0"),HookStubs.questions(List.of("q")), null, null);Hooks.Policy policy = Hooks.Policy.raising().timeout(Duration.ofMillis(50));@@ -858,4 +941,417 @@ final class HooksTest {assertTrue(HookCall.none().isEmpty());assertFalse(HookCall.none().raiseErrors(true).isEmpty());}++ // -- the defects an adversarial review reproduced -----------------------++ @Test+ @DisplayName("a scope removes the MOST RECENT copy, which is an order and not just a count")+ @SuppressWarnings("try")+ void aScopeRemovesTheMostRecentCopy() {+ HookRegistry registry = new HookRegistry();+ List<Object> log = new ArrayList<>();+ Hook own = HookStubs.hook(log, "own");+ Hook other = HookStubs.hook(log, "other");+ registry.addHook(own);+ registry.addHook(other);+ try (HookRegistry.Scope scope = registry.hooksInstalled(own)) {+ assertEquals(List.of("own", "other", "own"), labels(registry.hooks()),+ "the scope's copy is appended, so the caller's own copy is the EARLIER one");+ }+ // The direction of the scan is observable after all. Scanning forward takes the copy at+ // index 0 and leaves [other, own]; scanning backward takes index 2 and leaves+ // [own, other]. Same multiset, different dispatch order -- and order is the one thing+ // about a hook list this port calls a contract, because it decides whether `own` sees+ // what `other` did or the other way round.+ assertEquals(List.of("own", "other"), labels(registry.hooks()),+ "a forward scan would leave [other, own] and silently reorder two hooks the "+ + "caller installed itself");+ }++ @Test+ @DisplayName("an Error is never swallowed, whatever raiseErrors says")+ void anErrorIsNeverSwallowed() {+ List<Object> log = new ArrayList<>();+ Hook fatal = new Hook() {+ @Override+ public void onPredictStart(PredictContext ctx) {+ // Not a RuntimeException. The reference catches `Exception` and deliberately not+ // `BaseException`, so a KeyboardInterrupt or a SystemExit is never swallowed by+ // a telemetry hook; on the JVM the same rule is "RuntimeException, not Error".+ throw new StackOverflowError("the hook recursed");+ }+ };+ Hook after = HookStubs.hook(log, "after");+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ List<String> reported = new ArrayList<>();+ Hooks.Policy swallowing =+ Hooks.Policy.raising().raiseErrors(false).onFailure(reported::add);++ StackOverflowError problem = assertThrows(StackOverflowError.class,+ () -> Hooks.dispatch(List.of(fatal, after), Hooks.Event.PREDICT_START, ctx,+ swallowing),+ "raiseErrors(false) governs a RuntimeException and nothing else; an "+ + "OutOfMemoryError reported as a line of text and carried on from is the same "+ + "mistake");+ assertEquals("the hook recursed", problem.getMessage(),+ "the Error itself reaches the caller, not something wrapping it");+ assertEquals(List.of(), reported,+ "...and the failure sink never saw it, so nothing logged it as handled");+ assertEquals(List.of(), log, "...and the rest of the chain did not run");+ }++ @Test+ @DisplayName("withoutDefaultHooks nests: an inner scope closing does not cancel the outer")+ @SuppressWarnings("try")+ void withoutDefaultHooksNests() {+ List<Object> log = new ArrayList<>();+ Hook probe = HookStubs.hook(log, "probe");+ Hooks.setDefaultHooks(List.of(probe));+ try (Hooks.DefaultsScope outer = Hooks.withoutDefaultHooks()) {+ try (Hooks.DefaultsScope inner = Hooks.withoutDefaultHooks()) {+ assertEquals(List.of(), Hooks.compose(List.of(), HookCall.none()));+ }+ // The close restores the value it FOUND, which was already "suppressed". Restoring a+ // literal false here instead would read as "the scope is over" and switch the+ // defaults back on inside a scope that is still open -- which is the whole reason the+ // reference uses `_SKIP_DEFAULTS.reset(token)` rather than `set(False)`.+ assertEquals(List.of(), Hooks.compose(List.of(), HookCall.none()),+ "the inner scope closing must not cancel the outer suppression");+ }+ assertEquals(List.of(probe), Hooks.compose(List.of(), HookCall.none()),+ "and the outer scope closing does restore them");+ }++ @Test+ @DisplayName("a hook that outran its deadline keeps running, on a daemon thread")+ void anAbandonedHookRunsOnADaemonThread() throws Exception {+ Parked parked = new Parked();+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ Hooks.Policy policy = Hooks.Policy.raising().timeout(Duration.ofMillis(50));+ try {+ assertThrows(Hooks.HookTimeoutException.class, () ->+ Hooks.dispatch(List.of(parked), Hooks.Event.PREDICT_START, ctx, policy));+ Thread runner = parked.ranOn.get();+ assertNotNull(runner, "the hook never started, so this proves nothing");+ assertEquals("laya-hook-timeout", runner.getName(),+ "the name is what makes an abandoned hook identifiable in a thread dump");+ assertTrue(runner.isAlive(),+ "the hook is still running -- which is the point: the deadline bounded the "+ + "WAIT, not the hook");+ assertTrue(runner.isDaemon(),+ "a non-daemon thread would hold the JVM open after the caller is finished, "+ + "so a timed-out hook could stop a process from exiting at all");+ } finally {+ parked.release();+ }+ }++ @Test+ @DisplayName("a 50ms deadline cuts the wait off near 50ms, not near a second")+ void theDeadlineIsActuallyTheDeadline() throws Exception {+ Parked parked = new Parked();+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ Hooks.Policy policy = Hooks.Policy.raising().timeout(Duration.ofMillis(50));+ try {+ long began = System.nanoTime();+ assertThrows(Hooks.HookTimeoutException.class, () ->+ Hooks.dispatch(List.of(parked), Hooks.Event.PREDICT_START, ctx, policy));+ double waited = (System.nanoTime() - began) / 1_000_000.0;+ // Two bounds, both loose on purpose. The lower one catches a deadline that is+ // IGNORED -- a wait that returns before the hook could possibly have finished makes+ // the outcome of a fast hook a race, which is the reason validateTimeout refuses a+ // zero. The upper one catches a deadline that is INFLATED: nothing else in the suite+ // noticed when every deadline was multiplied by twenty, because the parked hook+ // never finishes either way and the only difference is how long the call waited.+ // 15x the deadline, not 1.2x, so a loaded machine cannot turn this red.+ assertTrue(waited >= 45.0,+ "the wait returned after " + waited + " ms on a 50 ms deadline, which is "+ + "before the hook could have finished");+ assertTrue(waited < 750.0,+ "a 50 ms deadline held the call for " + waited + " ms");+ } finally {+ parked.release();+ }+ }++ @Test+ @DisplayName("being interrupted while waiting for a hook restores the flag before wrapping it")+ void interruptWhileWaitingRestoresTheFlag() throws Exception {+ Parked parked = new Parked();+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ // Long enough that the deadline cannot be what ends the wait.+ Hooks.Policy policy = Hooks.Policy.raising().timeout(Duration.ofSeconds(30));+ AtomicReference<Throwable> thrown = new AtomicReference<>();+ AtomicReference<Boolean> flagAfterwards = new AtomicReference<>();+ Thread waiter = new Thread(() -> {+ try {+ Hooks.dispatch(List.of(parked), Hooks.Event.PREDICT_START, ctx, policy);+ } catch (RuntimeException problem) {+ thrown.set(problem);+ flagAfterwards.set(Thread.currentThread().isInterrupted());+ }+ }, "interrupt-while-waiting");+ try {+ waiter.start();+ assertTrue(parked.entered.await(10, TimeUnit.SECONDS),+ "the hook must be inside its event before its waiter is interrupted");+ waiter.interrupt();+ waiter.join(10_000);+ assertNotNull(thrown.get(), "the waiter was interrupted and did not report it");+ assertEquals(IllegalStateException.class, thrown.get().getClass());+ assertTrue(thrown.get().getMessage()+ .startsWith("interrupted while waiting for hook "),+ "the message named: " + thrown.get().getMessage());+ // Catching InterruptedException CLEARS the flag. Re-asserting it is the only thing+ // that keeps a shutdown request alive: a caller up the stack polling+ // Thread.interrupted() would otherwise be told it was never asked to stop.+ assertTrue(Boolean.TRUE.equals(flagAfterwards.get()),+ "the interrupt flag was swallowed along with the exception");+ } finally {+ parked.release();+ }+ }++ @Test+ @DisplayName("a hook cut off by its deadline can no longer write to the call")+ void anAbandonedHookCannotWriteToTheCall() throws Exception {+ Parked parked = new Parked(ctx -> ctx.results(List.of(HookStubs.result(999))));+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ Hooks.Policy policy = Hooks.Policy.raising().timeout(Duration.ofMillis(50));+ assertThrows(Hooks.HookTimeoutException.class, () ->+ Hooks.dispatch(List.of(parked), Hooks.Event.PREDICT_START, ctx, policy));+ // The call carries on without it, which is what the deadline is for.+ ctx.results(List.of(HookStubs.result(111)));+ parked.release();++ assertNotNull(parked.refused.get(),+ "the abandoned hook's write was ACCEPTED, so a hook the call stopped waiting for "+ + "can still rewrite the answer the caller already has");+ assertEquals(IllegalStateException.class, parked.refused.get().getClass());+ // `HookStubs.result(i)` reports `10 + i` input tokens, so this is the 111 above and not+ // the 999 the abandoned hook tried to put there.+ assertEquals(tokens(List.of(HookStubs.result(111))), tokens(ctx.results()),+ "...and the call kept the answer it had moved on with");+ }++ @Test+ @DisplayName("the overrun line names the hook and spells the deadline as the reference does")+ void theOverrunLineIsGreppableAcrossBothRuntimes() throws Exception {+ Parked parked = new Parked();+ // Through the convenience wrapper, which is the shape most likely to be named in one of+ // these lines and the shape that used to report no name at all.+ Hook wrapped = Hooks.onPredictStart(parked::onPredictStart);+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ try {+ Hooks.HookTimeoutException problem = assertThrows(Hooks.HookTimeoutException.class,+ () -> Hooks.dispatch(List.of(wrapped), Hooks.Event.PREDICT_START, ctx,+ Hooks.Policy.raising().timeout(Duration.ofSeconds(1))));+ // Two divergences in one line, both measured against CPython:+ // "exceeded 1.0s" -- %s on a double, where the reference's %g gives "1s", and a+ // whole number of seconds is the common case for a deadline;+ // "hook .on_" -- getSimpleName() of the anonymous class this wrapper used to+ // return is the EMPTY string, where the reference's+ // __qualname__ is "_StartAdapter.on_predict_start".+ assertEquals("laya: hook _StartAdapter.on_predict_start exceeded 1s",+ problem.getMessage());+ } finally {+ parked.release();+ }+ }++ @Test+ @DisplayName("the convenience callbacks name themselves when their failure is swallowed")+ void convenienceHooksAreNamedInTheirOwnFailureLine() {+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ List<String> reported = new ArrayList<>();+ Hooks.Policy swallowing =+ Hooks.Policy.raising().raiseErrors(false).onFailure(reported::add);++ Hooks.dispatch(List.of(Hooks.onPredictStart(seen -> {+ throw new IllegalArgumentException("boom");+ })), Hooks.Event.PREDICT_START, ctx, swallowing);+ Hooks.dispatch(List.of(Hooks.onPredictEnd(seen -> {+ throw new IllegalArgumentException("bang");+ })), Hooks.Event.PREDICT_END, ctx, swallowing);++ // raiseErrors(false) exists for a telemetry hook, and this line is the ONLY trace such a+ // hook's failure leaves. An empty name makes it untraceable to the hook that produced it.+ assertEquals(List.of("laya: hook _StartAdapter.on_predict_start failed: boom",+ "laya: hook _EndAdapter.on_predict_end failed: bang"), reported,+ "the reference names these _StartAdapter/_EndAdapter, and an anonymous Java "+ + "class names nothing");+ }++ @Test+ @DisplayName("a caller's own anonymous hook still has a name, which the reference cannot lack")+ void anAnonymousHookStillReportsAName() {+ PredictContext ctx = new PredictContext(List.of("s0"),+ HookStubs.questions(List.of("q")), null, null);+ List<String> reported = new ArrayList<>();+ Hooks.dispatch(List.of(new Hook() {+ @Override+ public void onPredictStart(PredictContext seen) {+ throw new IllegalArgumentException("boom");+ }+ }), Hooks.Event.PREDICT_START, ctx,+ Hooks.Policy.raising().raiseErrors(false).onFailure(reported::add));++ assertEquals(1, reported.size());+ // Python has no anonymous class and `__qualname__` always names something, so there is+ // no reference behaviour to match here -- only a line that must not be blank.+ assertTrue(reported.get(0).startsWith("laya: hook HooksTest$"),+ "an anonymous hook reported: " + reported.get(0));+ assertFalse(reported.get(0).contains("hook ."),+ "getSimpleName() of an anonymous class is the empty string, which left the hook "+ + "unnamed in the one line its swallowed failure produces");+ }++ @Test+ @DisplayName("usage totals do not wrap where the reference cannot wrap")+ void usageTotalsDoNotOverflow() {+ List<Prediction> huge = new ArrayList<>();+ for (int i = 0; i < 3; i++) {+ huge.add(new Prediction(Prediction.MODEL, Map.of(),+ new Usage(1_000_000_000, 1_000_000_000, 0, 0, false, List.of(), Map.of())));+ }+ Hooks.Totals got = Hooks.aggregateUsage(huge);+ // An int accumulator gives -1294967296, which no Python int can produce. `usage` is what+ // a metering hook bills from, so a wrap there is a wrong invoice rather than a wrong log.+ assertEquals(3_000_000_000L, got.inputTokens(),+ "three billion input tokens wrapped into an int accumulator");+ assertEquals(3_000_000_000L, got.outputTokens());+ }++ @Test+ @DisplayName("a null hook is refused by name from every entry point that takes one")+ void aNullHookIsRefusedByNameEverywhere() {+ String expected = "a hooks entry must not be null";+ // Each of these wrapped the hook in List.of(...) first, so the caller got a bare NPE+ // from inside the JDK and the message below was unreachable from all four.+ assertEquals(expected, assertThrows(IllegalArgumentException.class,+ () -> Hooks.addDefaultHook(null)).getMessage());+ assertEquals(expected, assertThrows(IllegalArgumentException.class,+ () -> new HookRegistry().addHook(null)).getMessage());+ assertEquals(expected, assertThrows(IllegalArgumentException.class,+ () -> HookCall.of((Hook) null)).getMessage());+ assertEquals(expected, assertThrows(IllegalArgumentException.class,+ () -> HookCall.none().andThen(null)).getMessage());+ List<Hook> withNull = new ArrayList<>();+ withNull.add(null);+ assertEquals(expected, assertThrows(IllegalArgumentException.class,+ () -> HookCall.of(withNull)).getMessage());+ }++ @Test+ @DisplayName("a context refuses a null states or questions by name, rather than NPEing")+ void aContextRefusesNullsByName() {+ Map<String, Question> questions = HookStubs.questions(List.of("q"));+ assertEquals("states must not be null", assertThrows(IllegalArgumentException.class,+ () -> new PredictContext(null, questions, null, null)).getMessage());+ // Before the hooks were wired in, `predictBatch(List.of(), null)` returned an empty list:+ // the empty-state short-circuit ran before anything looked at the questions. It now+ // refuses, which is what the reference does for an empty batch as much as any other --+ // its own check is `questions must be a dict of question id -> definition`, reached even+ // when `states` is empty. Tolerating the null instead would answer a real batch with+ // empty answers and zero usage.+ assertEquals("questions must not be null", assertThrows(IllegalArgumentException.class,+ () -> new PredictContext(List.of(), null, null, null)).getMessage());+ assertEquals("questions must not be null", assertThrows(IllegalArgumentException.class,+ () -> new PredictContext(List.of("s0"), null, null, null)).getMessage());+ }++ /**+ * No test may leave a hook thread running past this class.+ *+ * <p>Every test here that abandons one releases it, except {@link #aSlowHookTimesOut}, which+ * cannot — not being able to is the behaviour it asserts — and which therefore sleeps for a+ * bounded second rather than the five it used to. This is what turns that bound into an+ * assertion instead of an intention: the review that found the rest of this commit observed+ * two abandoned {@code laya-hook-timeout} threads alive in the middle of a run of the+ * shipped suite, and a leak nobody counts is a leak that grows.+ */+ @AfterAll+ static void noAbandonedHookThreadOutlivesTheSuite() throws InterruptedException {+ List<Thread> lingering = new ArrayList<>();+ for (Thread thread : Thread.getAllStackTraces().keySet()) {+ if ("laya-hook-timeout".equals(thread.getName())) {+ lingering.add(thread);+ }+ }+ for (Thread thread : lingering) {+ thread.join(10_000);+ }+ List<String> stuck = new ArrayList<>();+ for (Thread thread : lingering) {+ if (thread.isAlive()) {+ stuck.add(thread.toString());+ }+ }+ assertEquals(List.of(), stuck,+ "a hook thread outlived the suite: a test abandoned it and nothing released it");+ }++ /**+ * A hook that parks inside its event until the test releases it.+ *+ * <p>A sleep would do the same job less well in both directions: it is a race against the+ * deadline at one end — the thing under test — and at the other it leaves a thread running+ * for however long it was given. This one is deterministic (the hook is provably still inside+ * {@code on_predict_start} when the deadline expires) and {@link #release} joins the thread,+ * so a test asserting that a hook CANNOT be stopped does not have to leak one to prove it.+ */+ private static final class Parked implements Hook {++ private final CountDownLatch entered = new CountDownLatch(1);+ private final CountDownLatch released = new CountDownLatch(1);+ private final AtomicReference<Thread> ranOn = new AtomicReference<>();+ private final AtomicReference<Throwable> refused = new AtomicReference<>();+ private final Consumer<PredictContext> afterRelease;++ Parked() {+ this(ctx -> {+ // Park and nothing more: the deadline is the subject, not what the hook does.+ });+ }++ Parked(Consumer<PredictContext> afterRelease) {+ this.afterRelease = afterRelease;+ }++ @Override+ public void onPredictStart(PredictContext ctx) {+ ranOn.set(Thread.currentThread());+ entered.countDown();+ try {+ released.await();+ } catch (InterruptedException interrupted) {+ Thread.currentThread().interrupt();+ return;+ }+ try {+ afterRelease.accept(ctx);+ } catch (RuntimeException problem) {+ refused.set(problem);+ }+ }++ /** Lets the parked hook finish, and waits for its thread to be gone. */+ void release() throws InterruptedException {+ released.countDown();+ Thread thread = ranOn.get();+ if (thread != null && thread != Thread.currentThread()) {+ thread.join(10_000);+ if (thread.isAlive()) {+ fail("the released hook thread did not finish");+ }+ }+ }+ }}diff --git a/laya-java/laya-java/src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension b/laya-java/laya-java/src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extensionnew file mode 100644index 00000000..eb1ddee9--- /dev/null+++ b/laya-java/laya-java/src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension@@ -0,0 +1,4 @@+# Auto-registered for every test class in this module; see the class javadoc. One entry only --+# this file is what `junit.jupiter.extensions.autodetection.enabled` in build.gradle.kts turns on,+# so anything added here applies everywhere without an @ExtendWith to find it by.+com.convaiinnovations.laya.DefaultHooksIsolationdiff --git a/laya-java/scripts/gen_fixtures.py b/laya-java/scripts/gen_fixtures.pyindex 5762344f..6e92c5fa 100644--- a/laya-java/scripts/gen_fixtures.py+++ b/laya-java/scripts/gen_fixtures.py@@ -3270,7 +3270,13 @@ HOOK_USAGE_CASES = [#: Values offered to `validate_timeout`.-HOOK_TIMEOUT_VALUES = [None, 1, 1.5, 0.05, "0.5", 0, 0.0, -1, -0.5,+#:+#: The whole seconds -- 1, 2, 10, 60 -- and 1e-07 are here for the RENDERING, not the validation:+#: `_call_hook` reports an overrun with `%g`, which prints `1` where a naive port prints `1.0`+#: and `1e-07` where it prints `1.0E-7`. A whole number of seconds is the common case for a+#: deadline, so it is the common case for that line, and `laya-java` compares its own formatter+#: against the `seconds` field below rather than against a string somebody typed.+HOOK_TIMEOUT_VALUES = [None, 1, 2, 10, 60, 1.5, 0.05, 1e-07, "0.5", 0, 0.0, -1, -0.5,float("nan"), float("inf"), float("-inf")]@@ -3568,10 +3574,14 @@ def hook_dispatch():accepted = validate_timeout(value)entry["accepted"] = Trueentry["value"] = accepted+ # Exactly the rendering `_call_hook` puts in its TimeoutError, which the port has to+ # reproduce character for character -- see that function and `HOOK_TIMEOUT_VALUES`.+ entry["seconds"] = None if accepted is None else "%g" % acceptedentry["error"] = Noneexcept (ValueError, OverflowError) as problem:entry["accepted"] = Falseentry["value"] = None+ entry["seconds"] = Noneentry["error"] = str(problem)timeouts.append(entry)