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
feat(java): dispatch router lifecycle hooks, and add AsyncHook
Adeshina Lasisi8339733a3ee6
diff --git a/laya-java/README.md b/laya-java/README.mdindex a72b3c4e..2f83f062 100644--- a/laya-java/README.md+++ b/laya-java/README.md@@ -18,9 +18,10 @@ state builder (`LayaEmail`), the abstention gate (`ConfidenceGate`), scanning athe context window (`predictLong`), schema-driven decisions (`Decisions.decide` / `decideBatch`),and the prediction hooks (`hooks`).-Not implemented yet: the `laya-java-client` HTTP module, Android. Hooks run on `predict` and-`predictBatch`; `Router` and `predictLong` do not dispatch them, and there is no `AsyncHook` — see-[Watching and shaping a call](#watching-and-shaping-a-call). **Not published to+Not implemented yet: the `laya-java-client` HTTP module, Android. `predictLong` dispatches no hook:+a scan is sized before a hook could rewrite what is asked, so it stays unhooked until the+reference's start probe and budget check are ported — see+[Watching and shaping a call](#watching-and-shaping-a-call) and [Router hooks](#router-hooks). **Not published toMaven Central** — see [Installing](#installing).## Where to go next@@ -477,6 +478,39 @@ and a JVM method call is already synchronous: a hook that wants asynchronous worblocks on it — `ship(ctx.results()).toCompletableFuture().join()` — bounded however your runtimewants, or by `timeout(Duration)`.+## Router hooks++`Router.hooks()` is its own registry, separate from any agent's. A router-level hook sees three+events no agent can:++| event | when |+|---|---|+| `onRoute` | after a checkpoint is chosen, from every branch of `route` |+| `onLoad` | after a checkpoint is built — not on a cache hit |+| `onEvict` | after one is dropped, by `maxLoaded`, `unload` or `unloadAll` |++`Router.predict` also dispatches one `onPredictStart`/`onPredictEnd` pair for the whole+route-and-answer call, with `onLoad` and `onEvict` landing inside it. The agent's own pair still+fires for the forward pass, so a router-level hook and an agent-level hook see different spans.++Hooks are dispatched outside the router's lock, so a hook may call back into the router —+including `loaded()` or another `predict` — without deadlocking.++`ctx.maxLen` / `ctx.headMaxLen` set by a router-level start hook are not honoured:+`Agent.predict` takes no budget arguments. An agent-level hook can still set them.++```java+router.hooks().addHook(new Hook() {+ @Override public void onRoute(PredictContext ctx) { log.info("routed to {}", ctx.model()); }+ @Override public void onEvict(PredictContext ctx) { meter.increment("evictions"); }+});+```++`AsyncHook.of(hook, executor)` runs a hook on a particular thread — a framework request scope, an+actor, a UI loop. It waits for the callback, so an exception still reaches the hook policy and the+mutable `PredictContext` is never read after the call has moved on. Pass a `Duration` to fail a+callback that overruns.+## Option orderA choice's options are positional: option N renders Nth and logit N is read back as the Nth label.diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.javaindex 69e807b6..8f333cef 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java@@ -1,5 +1,10 @@package com.convaiinnovations.laya;+import com.convaiinnovations.laya.hooks.Hook;+import com.convaiinnovations.laya.hooks.HookCall;+import com.convaiinnovations.laya.hooks.HookRegistry;+import com.convaiinnovations.laya.hooks.Hooks;+import com.convaiinnovations.laya.hooks.PredictContext;import com.convaiinnovations.laya.json.PythonJson;import com.convaiinnovations.laya.lang.LanguageDetection;import com.convaiinnovations.laya.lang.UnicodeTables;@@ -367,6 +372,12 @@ public final class Router implements AutoCloseable, Predictor {private final LanguageHint langGuess;private final AgentFactory agents;+ /**+ * This router's hooks, separate from any agent's: these see {@code on_route}, {@code on_load}+ * and {@code on_evict}, and one predict pair for the whole route-and-answer call.+ */+ private final HookRegistry hooks = new HookRegistry();+private final ReentrantLock lock = new ReentrantLock();/** Serialises builds, so two cold loads do not hold two checkpoints in flight at once. */private final ReentrantLock buildLock = new ReentrantLock();@@ -725,6 +736,16 @@ public final class Router implements AutoCloseable, Predictor {*/public RouteDecision route(Object state, Map<String, Question> questions,RouteOptions options) {+ RouteDecision decision = decide(state, questions, options);+ // One dispatch point: `decide` returns from six branches, and a hook that fired from five+ // of them would be worse than none.+ dispatchLifecycle(Hooks.Event.ROUTE, decision.model());+ return decision;+ }++ /** The routing itself, with no hooks, so {@link #route} has a single place to dispatch from. */+ private RouteDecision decide(Object state, Map<String, Question> questions,+ RouteOptions options) {RouteOptions settings = options == null ? RouteOptions.none() : options;if (settings.model() != null) {@@ -851,7 +872,10 @@ public final class Router implements AutoCloseable, Predictor {/** Borrow the agent for a checkpoint. */public Lease lease(Checkpoint checkpoint) {requireNonNull(checkpoint, "checkpoint");- Slot slot = acquire(checkpoint);+ Outcome outcome = new Outcome();+ Slot slot = acquire(checkpoint, outcome);+ // Before the Lease is handed over, so on_load precedes any use of the agent.+ dispatchOutcome(checkpoint, outcome);return new Lease(checkpoint, slot);}@@ -867,13 +891,55 @@ public final class Router implements AutoCloseable, Predictor {*/public Agent load(String name) {Checkpoint checkpoint = normaliseName(name);- Slot slot = acquire(checkpoint);+ Outcome outcome = new Outcome();+ Slot slot = acquire(checkpoint, outcome);release(slot);+ // After release: a hook calling back in must not find this call still holding a lease.+ dispatchOutcome(checkpoint, outcome);return slot.agent;}+ /**+ * What one {@link #acquire} did, so its hooks fire after the lock is released. Dispatching+ * under {@code lock} would let a blocking hook park every other caller.+ */+ private static final class Outcome {++ private boolean built;+ private final List<Checkpoint> evicted = new ArrayList<>();+ }++ /**+ * Dispatch one router lifecycle event. MUST be called with no router lock held -- see+ * {@link Outcome}.+ */+ private void dispatchLifecycle(Hooks.Event event, Checkpoint checkpoint) {+ List<Hook> composed = hooks.composeFor(HookCall.none());+ if (composed.isEmpty()) {+ return; // no hooks: build no context, resolve no policy+ }+ PredictContext ctx = new PredictContext(List.of(), Map.of(),+ checkpoint == null ? null : checkpoint.wireName(), this);+ Hooks.dispatch(composed, event, ctx, hooks.policyFor(HookCall.none()));+ }++ /** The load and evict events one acquire owes, in that order. */+ private void dispatchOutcome(Checkpoint checkpoint, Outcome outcome) {+ if (outcome.built) {+ dispatchLifecycle(Hooks.Event.LOAD, checkpoint);+ }+ for (Checkpoint evicted : outcome.evicted) {+ dispatchLifecycle(Hooks.Event.EVICT, evicted);+ }+ }+/** The slot for a checkpoint, with one lease taken. */private Slot acquire(Checkpoint checkpoint) {+ return acquire(checkpoint, null);+ }++ /** The slot for a checkpoint, recording into {@code outcome} what it had to do to get it. */+ private Slot acquire(Checkpoint checkpoint, Outcome outcome) {while (true) {InFlight waitFor = null;InFlight mine = null;@@ -903,7 +969,7 @@ public final class Router implements AutoCloseable, Predictor {// This caller owns the build, and `mine` is the handle the others are waiting on.// It has to be the one registered above: creating a second one here would leave// every waiter blocked on a latch nobody ever counts down.- return build(checkpoint, mine);+ return build(checkpoint, mine, outcome);}// Someone else is building this one. Wait for them rather than build a second copy.await(waitFor);@@ -919,7 +985,7 @@ public final class Router implements AutoCloseable, Predictor {}}- private Slot build(Checkpoint checkpoint, InFlight inflight) {+ private Slot build(Checkpoint checkpoint, InFlight inflight, Outcome outcome) {List<Agent> toClose = new ArrayList<>();Slot built;try {@@ -964,7 +1030,11 @@ public final class Router implements AutoCloseable, Predictor {built.leases++;slots.put(checkpoint, built);order.add(checkpoint);- evictLocked(toClose);+ List<Checkpoint> evicted = evictLocked(toClose);+ if (outcome != null) {+ outcome.built = true;+ outcome.evicted.addAll(evicted);+ }}} finally {// `finish` ALWAYS, even if eviction threw. Skipping it left the new slot@@ -1236,6 +1306,9 @@ public final class Router implements AutoCloseable, Predictor {}if (inflight == null) {closeAll(toClose);+ for (Checkpoint evicted : freed) {+ dispatchLifecycle(Hooks.Event.EVICT, evicted);+ }return freed;}await(inflight);@@ -1264,6 +1337,9 @@ public final class Router implements AutoCloseable, Predictor {}if (inflights.isEmpty()) {closeAll(toClose);+ for (Checkpoint evicted : freed) {+ dispatchLifecycle(Hooks.Event.EVICT, evicted);+ }return freed;}for (InFlight inflight : inflights) {@@ -1290,6 +1366,11 @@ public final class Router implements AutoCloseable, Predictor {* ceiling in place. That is the reference's behaviour and is kept deliberately; a caller who* needs the original ceiling back should build a new router.*/+ /** This router's hooks: install, remove, and set the error, timeout and concurrency policy. */+ public HookRegistry hooks() {+ return hooks;+ }+public int maxLoaded() {lock.lock();try {@@ -1333,9 +1414,36 @@ public final class Router implements AutoCloseable, Predictor {if (language == null && decision.detection() != null) {language = decision.detection().language();}- try (Lease lease = lease(decision.model())) {- return lease.agent().predict(state, questions, language);+ List<Hook> composed = hooks.composeFor(HookCall.none());+ if (composed.isEmpty()) {+ try (Lease lease = lease(decision.model())) {+ return lease.agent().predict(state, questions, language); // unchanged fast path+ }+ }+ // `Hooks.around` so ctx.skip, the error-before-end order, failure suppression and+ // elapsed/usage all behave as they do on an Agent. The lease is taken inside it, so+ // on_load and on_evict land between this call's start and end events.+ //+ // ctx.maxLen/headMaxLen are NOT forwarded: Agent.predict takes no budget arguments, so a+ // Router-level start hook that sets one is ignored here.+ PredictContext ctx = new PredictContext(Collections.singletonList(state), questions,+ decision.model().wireName(), this);+ String resolved = language;+ Checkpoint target = decision.model();+ List<Prediction> answered = Hooks.around(composed, ctx,+ hooks.policyFor(HookCall.none()),+ (states, asked, maxLen, headMaxLen) -> {+ try (Lease lease = lease(target)) {+ return List.of(lease.agent().predict(states.get(0), asked, resolved));+ }+ });+ if (answered == null || answered.isEmpty()) {+ // Only a hook can cause this, by skipping with no result. Inventing one would report+ // a decision the model never made.+ throw new IllegalStateException(+ "a hook left no prediction for this call; ctx.skip(...) needs one result");}+ return answered.get(0);}/**diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.javanew file mode 100644index 00000000..b27f8b63--- /dev/null+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.java@@ -0,0 +1,130 @@+package com.convaiinnovations.laya.hooks;++import java.time.Duration;+import java.util.Objects;+import java.util.concurrent.CompletableFuture;+import java.util.concurrent.CompletionException;+import java.util.concurrent.Executor;+import java.util.concurrent.TimeUnit;+import java.util.concurrent.TimeoutException;++/**+ * Runs another hook's callbacks on an {@link Executor}, and waits for each one.+ *+ * <p>For a hook that must run on a particular thread -- a framework request scope, a single-threaded+ * actor, a UI loop -- not for making a slow hook free. The reference does the same: an async hook's+ * coroutine is driven to completion on a background loop ({@code laya/hooks.run_coroutine_sync}), so+ * the prediction still waits for it.+ *+ * <p>Waiting is what makes it safe. {@link PredictContext} is mutable and shared by one call, so a+ * callback still reading it after the call moved on would see another call's state; a thrown+ * exception would also be lost rather than reaching the hook policy.+ */+public final class AsyncHook implements Hook {++ private final Hook delegate;+ private final Executor executor;+ private final Duration timeout;++ private AsyncHook(Hook delegate, Executor executor, Duration timeout) {+ this.delegate = Objects.requireNonNull(delegate, "delegate");+ this.executor = Objects.requireNonNull(executor, "executor");+ this.timeout = timeout;+ }++ /** Runs {@code delegate} on {@code executor}, waiting indefinitely for each callback. */+ public static AsyncHook of(Hook delegate, Executor executor) {+ return new AsyncHook(delegate, executor, null);+ }++ /**+ * Runs {@code delegate} on {@code executor}, failing a callback that outlasts {@code timeout}.+ *+ * <p>Independent of {@code hooks_timeout}: that one bounds the whole dispatch and is not visible+ * to a hook, so this one has to be given here.+ */+ public static AsyncHook of(Hook delegate, Executor executor, Duration timeout) {+ if (timeout != null && (timeout.isNegative() || timeout.isZero())) {+ throw new IllegalArgumentException("timeout must be positive, got " + timeout);+ }+ return new AsyncHook(delegate, executor, timeout);+ }++ /** The hook whose callbacks this runs. */+ public Hook delegate() {+ return delegate;+ }++ @Override+ public void onPredictStart(PredictContext ctx) {+ await("on_predict_start", () -> delegate.onPredictStart(ctx));+ }++ @Override+ public void onPredictEnd(PredictContext ctx) {+ await("on_predict_end", () -> delegate.onPredictEnd(ctx));+ }++ @Override+ public void onRoute(PredictContext ctx) {+ await("on_route", () -> delegate.onRoute(ctx));+ }++ @Override+ public void onLoad(PredictContext ctx) {+ await("on_load", () -> delegate.onLoad(ctx));+ }++ @Override+ public void onEvict(PredictContext ctx) {+ await("on_evict", () -> delegate.onEvict(ctx));+ }++ @Override+ public void onError(PredictContext ctx) {+ await("on_error", () -> delegate.onError(ctx));+ }++ private void await(String event, Runnable callback) {+ CompletableFuture<Void> running;+ try {+ running = CompletableFuture.runAsync(callback, executor);+ } catch (RuntimeException rejected) {+ // A saturated or shut-down executor. Thrown as-is so the hook policy decides, exactly+ // as it would for a synchronous hook that threw.+ throw rejected;+ }+ try {+ if (timeout == null) {+ running.join();+ } else {+ running.get(timeout.toNanos(), TimeUnit.NANOSECONDS);+ }+ } catch (CompletionException | java.util.concurrent.ExecutionException wrapper) {+ // Unwrapped, so the caller sees what the delegate threw rather than the plumbing.+ Throwable cause = wrapper.getCause() == null ? wrapper : wrapper.getCause();+ if (cause instanceof RuntimeException problem) {+ throw problem;+ }+ if (cause instanceof Error problem) {+ throw problem;+ }+ throw new IllegalStateException(delegate + " failed in " + event, cause);+ } catch (TimeoutException expired) {+ running.cancel(true);+ throw new IllegalStateException(+ delegate + " did not finish " + event + " within " + timeout, expired);+ } catch (InterruptedException interrupted) {+ // The flag is restored before unwinding, so a caller using interruption to cancel is+ // not left thinking the interrupt was swallowed.+ Thread.currentThread().interrupt();+ running.cancel(true);+ throw new IllegalStateException(delegate + " was interrupted in " + event, interrupted);+ }+ }++ @Override+ public String toString() {+ return "AsyncHook(" + delegate + (timeout == null ? "" : ", timeout=" + timeout) + ")";+ }+}diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.javanew file mode 100644index 00000000..b599c04c--- /dev/null+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.java@@ -0,0 +1,180 @@+package com.convaiinnovations.laya;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertNotEquals;+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 com.convaiinnovations.laya.hooks.AsyncHook;+import com.convaiinnovations.laya.hooks.Hook;+import com.convaiinnovations.laya.hooks.PredictContext;+import java.time.Duration;+import java.util.ArrayList;+import java.util.List;+import java.util.Map;+import java.util.concurrent.CountDownLatch;+import java.util.concurrent.ExecutorService;+import java.util.concurrent.Executors;+import java.util.concurrent.atomic.AtomicReference;+import org.junit.jupiter.api.DisplayName;+import org.junit.jupiter.api.Test;++/** {@link AsyncHook} runs a hook elsewhere but still waits for it, as the reference does. */+class AsyncHookTest {++ private static PredictContext ctx() {+ return new PredictContext(List.of("state"), Map.of(), "english", null);+ }++ @Test+ @DisplayName("the callback runs on the executor, not the calling thread")+ void runsOnTheExecutor() {+ ExecutorService pool = Executors.newSingleThreadExecutor(r -> new Thread(r, "hook-pool"));+ try {+ AtomicReference<String> ran = new AtomicReference<>();+ Hook async = AsyncHook.of(new Hook() {+ @Override+ public void onPredictStart(PredictContext c) {+ ran.set(Thread.currentThread().getName());+ }+ }, pool);+ async.onPredictStart(ctx());+ assertEquals("hook-pool", ran.get());+ assertNotEquals(Thread.currentThread().getName(), ran.get());+ } finally {+ pool.shutdownNow();+ }+ }++ @Test+ @DisplayName("the call waits: the callback has finished before the method returns")+ void waitsForTheCallback() {+ ExecutorService pool = Executors.newSingleThreadExecutor();+ try {+ CountDownLatch done = new CountDownLatch(1);+ Hook async = AsyncHook.of(new Hook() {+ @Override+ public void onPredictStart(PredictContext c) {+ try {+ Thread.sleep(50);+ } catch (InterruptedException e) {+ Thread.currentThread().interrupt();+ }+ done.countDown();+ }+ }, pool);+ async.onPredictStart(ctx());+ assertEquals(0, done.getCount(), "returned before the callback finished");+ } finally {+ pool.shutdownNow();+ }+ }++ @Test+ @DisplayName("the delegate's exception reaches the caller unwrapped, so the policy sees it")+ void propagatesTheDelegateFailure() {+ ExecutorService pool = Executors.newSingleThreadExecutor();+ try {+ IllegalStateException boom = new IllegalStateException("from the hook");+ Hook async = AsyncHook.of(new Hook() {+ @Override+ public void onPredictEnd(PredictContext c) {+ throw boom;+ }+ }, pool);+ assertSame(boom, assertThrows(IllegalStateException.class,+ () -> async.onPredictEnd(ctx())));+ } finally {+ pool.shutdownNow();+ }+ }++ @Test+ @DisplayName("a callback that outlasts the timeout fails the dispatch")+ void timesOut() {+ ExecutorService pool = Executors.newSingleThreadExecutor();+ try {+ Hook async = AsyncHook.of(new Hook() {+ @Override+ public void onRoute(PredictContext c) {+ try {+ Thread.sleep(5_000);+ } catch (InterruptedException e) {+ Thread.currentThread().interrupt();+ }+ }+ }, pool, Duration.ofMillis(50));+ IllegalStateException thrown =+ assertThrows(IllegalStateException.class, () -> async.onRoute(ctx()));+ assertTrue(thrown.getMessage().contains("did not finish"), thrown.getMessage());+ } finally {+ pool.shutdownNow();+ }+ }++ @Test+ @DisplayName("a non-positive timeout is refused rather than meaning 'never wait'")+ void refusesANonPositiveTimeout() {+ ExecutorService pool = Executors.newSingleThreadExecutor();+ try {+ Hook plain = new Hook() { };+ assertThrows(IllegalArgumentException.class,+ () -> AsyncHook.of(plain, pool, Duration.ZERO));+ assertThrows(IllegalArgumentException.class,+ () -> AsyncHook.of(plain, pool, Duration.ofMillis(-1)));+ } finally {+ pool.shutdownNow();+ }+ }++ @Test+ @DisplayName("every event is forwarded, not just the predict pair")+ void forwardsEveryEvent() {+ ExecutorService pool = Executors.newSingleThreadExecutor();+ try {+ List<String> seen = new ArrayList<>();+ Hook async = AsyncHook.of(new Hook() {+ @Override+ public void onPredictStart(PredictContext c) {+ seen.add("start");+ }++ @Override+ public void onPredictEnd(PredictContext c) {+ seen.add("end");+ }++ @Override+ public void onRoute(PredictContext c) {+ seen.add("route");+ }++ @Override+ public void onLoad(PredictContext c) {+ seen.add("load");+ }++ @Override+ public void onEvict(PredictContext c) {+ seen.add("evict");+ }++ @Override+ public void onError(PredictContext c) {+ seen.add("error");+ }+ }, pool);+ PredictContext ctx = ctx();+ async.onPredictStart(ctx);+ async.onRoute(ctx);+ async.onLoad(ctx);+ async.onEvict(ctx);+ async.onError(ctx);+ async.onPredictEnd(ctx);+ assertEquals(List.of("start", "route", "load", "evict", "error", "end"), seen);+ } finally {+ pool.shutdownNow();+ }+ }+}diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.javanew file mode 100644index 00000000..f7f79757--- /dev/null+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.java@@ -0,0 +1,186 @@+package com.convaiinnovations.laya;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertFalse;+import static org.junit.jupiter.api.Assertions.assertTrue;++import com.convaiinnovations.laya.Router.Checkpoint;+import com.convaiinnovations.laya.hooks.Hook;+import com.convaiinnovations.laya.hooks.PredictContext;+import java.io.IOException;+import java.nio.file.Path;+import java.util.ArrayList;+import java.util.List;+import java.util.Map;+import org.junit.jupiter.api.DisplayName;+import org.junit.jupiter.api.Test;+import org.junit.jupiter.api.io.TempDir;++/**+ * A Router-level hook sees what no agent can: which checkpoint was chosen, and when one was built+ * or dropped. Before this, {@code Router} dispatched nothing at all.+ */+class RouterHooksTest {++ /** Records every event with the model it carried. */+ private static final class Trace implements Hook {++ final List<String> events = new ArrayList<>();++ private void note(String event, PredictContext ctx) {+ events.add(event + ":" + ctx.model());+ }++ @Override+ public void onRoute(PredictContext ctx) {+ note("route", ctx);+ }++ @Override+ public void onLoad(PredictContext ctx) {+ note("load", ctx);+ }++ @Override+ public void onEvict(PredictContext ctx) {+ note("evict", ctx);+ }++ @Override+ public void onPredictStart(PredictContext ctx) {+ note("start", ctx);+ }++ @Override+ public void onPredictEnd(PredictContext ctx) {+ note("end", ctx);+ }+ }++ private static final class StubAgents implements Router.AgentFactory {++ private final Path root;+ int builds;++ StubAgents(Path root) {+ this.root = root;+ }++ @Override+ public Agent create(Checkpoint checkpoint) throws IOException {+ builds++;+ return TinyCheckpoint.agent(root, new TinyCheckpoint.RecordingSession());+ }+ }++ private static Map<String, Question> questions() {+ return Map.of("urgent", Question.noul("Needs a human."));+ }++ @Test+ @DisplayName("route() dispatches on_route once, naming the checkpoint it chose")+ void routeDispatches(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ Trace trace = new Trace();+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {+ router.hooks().addHook(trace);+ router.route("hello", questions());+ assertEquals(1, trace.events.size(), trace.events.toString());+ assertTrue(trace.events.get(0).startsWith("route:"), trace.events.toString());+ }+ }++ @Test+ @DisplayName("load() dispatches on_load for a build and stays quiet for a cache hit")+ void loadDispatchesOnlyOnBuild(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ Trace trace = new Trace();+ StubAgents agents = new StubAgents(root);+ try (Router router = Router.builder().agents(agents).maxLoaded(2).build()) {+ router.hooks().addHook(trace);+ router.load("english");+ assertEquals(List.of("load:english"), trace.events);+ router.load("english"); // resident: no second build, no second event+ assertEquals(List.of("load:english"), trace.events);+ assertEquals(1, agents.builds);+ }+ }++ @Test+ @DisplayName("an eviction forced by maxLoaded dispatches on_evict for the victim")+ void evictionDispatches(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ Trace trace = new Trace();+ try (Router router = Router.builder().agents(new StubAgents(root)).maxLoaded(1).build()) {+ router.hooks().addHook(trace);+ router.load("english");+ router.load("multilingual"); // maxLoaded 1, so english must go+ assertTrue(trace.events.contains("evict:english"), trace.events.toString());+ assertEquals(List.of("load:english", "load:multilingual", "evict:english"),+ trace.events);+ }+ }++ @Test+ @DisplayName("unload dispatches on_evict for what it freed")+ void unloadDispatches(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ Trace trace = new Trace();+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {+ router.load("english");+ router.hooks().addHook(trace); // installed after the load+ assertEquals(List.of(Checkpoint.ENGLISH), router.unload("english"));+ assertEquals(List.of("evict:english"), trace.events);+ }+ }++ @Test+ @DisplayName("predict dispatches one start/end pair for the whole route-and-answer call")+ void predictDispatchesOnePair(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ Trace trace = new Trace();+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {+ router.hooks().addHook(trace);+ router.predict("hello", questions());+ assertEquals(1, trace.events.stream().filter(e -> e.startsWith("start:")).count(),+ trace.events.toString());+ assertEquals(1, trace.events.stream().filter(e -> e.startsWith("end:")).count(),+ trace.events.toString());+ // on_load lands inside the pair, which is the order the reference dispatches in.+ int start = trace.events.indexOf("start:english");+ int load = trace.events.indexOf("load:english");+ int end = trace.events.indexOf("end:english");+ assertTrue(start >= 0 && load > start && end > load, trace.events.toString());+ }+ }++ @Test+ @DisplayName("a hook that calls back into the router does not deadlock")+ void aReentrantHookDoesNotDeadlock(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ List<Integer> seen = new ArrayList<>();+ try (Router router = Router.builder().agents(new StubAgents(root)).maxLoaded(2).build()) {+ // Dispatching under the router lock would park this call on itself for ever.+ router.hooks().addHook(new Hook() {+ @Override+ public void onLoad(PredictContext ctx) {+ seen.add(router.loaded().size());+ }+ });+ router.load("english");+ assertEquals(List.of(1), seen);+ }+ }++ @Test+ @DisplayName("a router with no hooks dispatches nothing and builds no context")+ void noHooksNoDispatch(@TempDir Path root) throws IOException {+ TinyCheckpoint.write(root, 64, 32);+ StubAgents agents = new StubAgents(root);+ try (Router router = Router.builder().agents(agents).build()) {+ assertFalse(router.hooks().hooks().iterator().hasNext());+ router.predict("hello", questions()); // the unhooked fast path still answers+ assertEquals(1, agents.builds);+ }+ }+}