core: Question.instructions() on the sealed interface; clearer local names

Every Question variant already had instructions(); declaring it on the
interface removes three type switches that only read it (Sonar S1871 in
ClefEngine). Also from Sonar: TokenCounter's private record(...) is count(...)
(restricted identifier, S6213), QwenEngine's token-id arrays are letterIds/
digitIds instead of letters/digits next to LETTERS/DIGITS (S1845), and its
empty Noul branch says why it's empty (S108).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- **`core`: `Question.instructions()`** — the sealed interface declares the accessor every variant already has, so callers read a question's instructions without switching on its type.
 - **Breaking: `JsonCodec` is now `Codec`, and it and `HttpTransport` speak `byte[]`** — `writeValueAsBytes`/`readValue(byte[], ...)` (no pretty-printing variant: the CLI's `--verbose` prints compact JSON), `Builder.codec(...)` (was `jsonCodec(...)`), and a `byte[]` request/response body, so JSON goes to and from the wire as UTF-8 with no `String` copy and a binary codec can implement the same SPI; `Jackson2Codec` now writes emoji and other non-BMP characters unescaped, like `Jackson3Codec`. (#35)
 - **Breaking: modules split into model (`core`), serialization (`codec`), contract (`client`) and implementations (`client-*`), names aligned** — `core` keeps the model; `Codec` is the new `codec` module; `TypeSafeClient`, `TypeSafeException` and the decorators move to the new `client`, and `DefaultTypeSafeClient`/`ApiKey`/`HttpTransport` to the new `client-http`; `TypeSafeClient.builder()` becomes `DefaultTypeSafeClient.builder()`, and every module's artifact and package now match its directory (`client-http-jdk`, `client-http-okhttp`, `codec-jackson2`, `codec-jackson3`, `client-local`, `client-mapping`, `client-testkit`); see ADR 0003. (#35)
 - **docs: local-model setup as three steps** — dependency, Laya download, code, then a model comparison; the optional Clef 4-bit script runs from its GitHub URL with `uv run`, and load errors link to the how-to.

client-local/src/main/java/io/github/dfa1/typesafe/client/local/ClefEngine.java

@@ -221,11 +221,7 @@ private static Map<String, String> options(Question question) {
     }
 
     private static Content instructions(Question question) {
-        Content c = switch (question) {
-            case Question.Noul q -> q.instructions();
-            case Question.Choice q -> q.instructions();
-            case Question.Score q -> q.instructions();
-        };
+        Content c = question.instructions();
         return c == null ? new Content.Text("") : c;
     }
 

client-local/src/main/java/io/github/dfa1/typesafe/client/local/LayaEngine.java

@@ -128,11 +128,7 @@ Sequence sequence(String state, Question question) {
             case Question.Score ignored -> "score";
             case Question.Noul ignored -> "noul";
         };
-        Content instructions = switch (question) {
-            case Question.Choice c -> c.instructions();
-            case Question.Score s -> s.instructions();
-            case Question.Noul n -> n.instructions();
-        };
+        Content instructions = question.instructions();
         long[] head = encode(type + " question: " + serialize(instructions).replace("[MASK]", " "));
         List<long[]> opts = new ArrayList<>();
         for (String option : options(question)) {

client-local/src/main/java/io/github/dfa1/typesafe/client/local/QwenEngine.java

@@ -29,7 +29,7 @@
 /**
  * Answers from a chat LLM's next-token logits, never from generated text: one prefill per
  * question, ending where the answer token goes, then a softmax over just the candidate tokens
- * ({@code Yes}/{@code No}, option letters, level digits). Deterministic, nothing to parse.
+ * ({@code Yes}/{@code No}, option letterIds, level digitIds). Deterministic, nothing to parse.
  * Prompted with Qwen2.5's ChatML template.
  */
 final class QwenEngine implements Engine {
@@ -54,8 +54,8 @@ interface Forward {
     private final Model model;
     private final int yes;
     private final int no;
-    private final int[] letters = new int[LETTERS.length()];
-    private final int[] digits = new int[DIGITS.length()];
+    private final int[] letterIds = new int[LETTERS.length()];
+    private final int[] digitIds = new int[DIGITS.length()];
 
     /** @param encode for the ChatML template, {@code encodeText} for the user turn (special tokens stay text) */
     QwenEngine(Function<String, long[]> encode, Function<String, long[]> encodeText, Forward forward, Runnable close,
@@ -67,11 +67,11 @@ interface Forward {
         this.model = model;
         this.yes = singleToken("Yes");
         this.no = singleToken("No");
-        for (int i = 0; i < letters.length; i++) {
-            letters[i] = singleToken(String.valueOf(LETTERS.charAt(i)));
+        for (int i = 0; i < letterIds.length; i++) {
+            letterIds[i] = singleToken(String.valueOf(LETTERS.charAt(i)));
         }
-        for (int i = 0; i < digits.length; i++) {
-            digits[i] = singleToken(String.valueOf(DIGITS.charAt(i)));
+        for (int i = 0; i < digitIds.length; i++) {
+            digitIds[i] = singleToken(String.valueOf(DIGITS.charAt(i)));
         }
     }
 
@@ -162,9 +162,9 @@ Answer answer(Question question, float[] logits) {
         return switch (question) {
             case Question.Noul ignored -> new Answer.Noul(Probabilities.softmax(logits[yes], logits[no])[0]);
             case Question.Choice(Content ignored, Map<String, String> criteria) ->
-                    Probabilities.choice(criteria, Probabilities.softmax(pick(logits, letters, criteria.size())));
+                    Probabilities.choice(criteria, Probabilities.softmax(pick(logits, letterIds, criteria.size())));
             case Question.Score(Content ignored, List<String> criteria) ->
-                    Probabilities.score(criteria, Probabilities.softmax(pick(logits, digits, criteria.size())));
+                    Probabilities.score(criteria, Probabilities.softmax(pick(logits, digitIds, criteria.size())));
         };
     }
 
@@ -180,6 +180,7 @@ private static float[] pick(float[] logits, int[] tokens, int n) {
     static void validate(String name, Question question) {
         switch (question) {
             case Question.Noul ignored -> {
+                // Yes/No: nothing to check
             }
             case Question.Choice(Content ignored, Map<String, String> criteria) -> {
                 if (criteria == null || criteria.isEmpty() || criteria.size() > LETTERS.length()) {

client-local/src/test/java/io/github/dfa1/typesafe/client/local/TokenizerInputs.java

@@ -42,11 +42,7 @@ public static void main(String[] args) throws Exception {
             Content state = c.request().state();
             laya.add(LayaEngine.serialize(state));
             for (Question q : c.request().questions().values()) {
-                Content instructions = switch (q) {
-                    case Question.Noul n -> n.instructions();
-                    case Question.Choice ch -> ch.instructions();
-                    case Question.Score s -> s.instructions();
-                };
+                Content instructions = q.instructions();
                 String type = switch (q) {
                     case Question.Noul ignored -> "noul";
                     case Question.Choice ignored -> "choice";

client/src/main/java/io/github/dfa1/typesafe/client/TokenCounter.java

@@ -51,7 +51,7 @@ public long totalTokens() {
         return inputTokens() + outputTokens();
     }
 
-    private EvaluateResponse record(EvaluateResponse response) {
+    private EvaluateResponse count(EvaluateResponse response) {
         Usage usage = response.usage();
         if (usage != null) {
             inputTokens.add(usage.inputTokens());
@@ -69,12 +69,12 @@ private final class Counting implements TypeSafeClient {
 
         @Override
         public EvaluateResponse evaluate(EvaluateRequest request) {
-            return record(delegate.evaluate(request));
+            return count(delegate.evaluate(request));
         }
 
         @Override
         public CompletableFuture<EvaluateResponse> evaluateAsync(EvaluateRequest request) {
-            return delegate.evaluateAsync(request).thenApply(TokenCounter.this::record);
+            return delegate.evaluateAsync(request).thenApply(TokenCounter.this::count);
         }
 
         @Override

core/src/main/java/io/github/dfa1/typesafe/core/Question.java

@@ -9,6 +9,9 @@
  */
 public sealed interface Question permits Question.Noul, Question.Choice, Question.Score {
 
+    /** What the question asks; every variant has one. */
+    Content instructions();
+
     static Noul noul(String instructions, Map<String, String> criteria) {
         return noul(Content.text(instructions), criteria);
     }

docs/reference.md

@@ -51,7 +51,8 @@ object holding the question in one field and data it refers to in others:
 | `Question.score(instructions, List<String> criteria)` | `instructions`, `criteria` | Rank against an ordered list of labels |
 
 Each `Question` variant's `instructions` component is typed `Content`, not `String` — see
-[`Content`](#content-sealed-interface) below.
+[`Content`](#content-sealed-interface) below — and `Question.instructions()` reads it from any
+variant, without a switch.
 
 ### `Answer` (sealed interface)