Skip to content

armgit / laya

Public Imported from GitHub
0

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

fix(java): twelve hook defects, and the measurement behind each fix

Adeshina Lasisie6571d8de0e9
diff --git a/.github/workflows/java.yml b/.github/workflows/java.yml
index 4018d945..73712f8b 100644
--- a/.github/workflows/java.yml
+++ b/.github/workflows/java.yml
@@ -156,18 +156,22 @@ jobs:
- name: Tests that need no model
working-directory: laya-java
run: ./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 vacuous
if: ${{ !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 JVM
if: ${{ !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.2
if: ${{ failure() }}
diff --git a/laya-java/CHANGELOG.md b/laya-java/CHANGELOG.md
index 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` run
it; `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 checkpoint
name a hook reads off `PredictContext.model()`. `Agent.open` takes it from the model
directory'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 compiled
for, because the toolchain pins the compiler to 17 and a lane that merely installs another JDK
tests 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 had
asserted that the JDK disagrees. Catching up is not a reason to drop the table -- it is the
diff --git a/laya-java/README.md b/laya-java/README.md
index 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 trac
watch 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)) { ... }`. It
removes one copy of each hook it added — not every copy by identity, which would take one the
diff --git a/laya-java/build.gradle.kts b/laya-java/build.gradle.kts
index 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.json
index 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.java
index 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>> onPredic
new 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.java
index 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.java
index 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&nbsp;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.java
index 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&nbsp;ms deadline by 30&nbsp;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&nbsp;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));
+ }
+ }
+
@Override
public 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.java
new file mode 100644
index 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.java
new file mode 100644
index 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.java
index 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.Extension
new file mode 100644
index 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.DefaultHooksIsolation
diff --git a/laya-java/scripts/gen_fixtures.py b/laya-java/scripts/gen_fixtures.py
index 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"] = True
entry["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" % accepted
entry["error"] = None
except (ValueError, OverflowError) as problem:
entry["accepted"] = False
entry["value"] = None
+ entry["seconds"] = None
entry["error"] = str(problem)
timeouts.append(entry)