@euconform/core 1.4.0 → 1.6.0

package/tests/fixtures/cyclonedx-minimal.json

@@ -0,0 +1,13 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "components": [
+    {
+      "type": "machine-learning-model",
+      "name": "llama-3.2-1b",
+      "version": "1.0.0",
+      "purl": "pkg:generic/llama-3.2-1b@1.0.0"
+    }
+  ]
+}

package/tests/fixtures/cyclonedx-mixed.json

@@ -0,0 +1,17 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "components": [
+    { "type": "library", "name": "express", "version": "4.18.2" },
+    { "type": "library", "name": "lodash", "version": "4.17.21" },
+    { "type": "library", "name": "openai", "version": "1.12.0" },
+    { "type": "framework", "name": "transformers", "version": "4.38.0" },
+    { "type": "library", "name": "chromadb", "version": "0.4.22" },
+    { "type": "library", "name": "langchain", "version": "0.1.0" },
+    { "type": "machine-learning-model", "name": "whisper-large-v3", "version": "1.0.0" },
+    { "type": "library", "name": "typescript", "version": "5.3.0" },
+    { "type": "library", "name": "react", "version": "18.2.0" },
+    { "type": "library", "name": "axios", "version": "1.6.0" }
+  ]
+}

package/tests/fixtures/cyclonedx-ml-bom.json

@@ -0,0 +1,25 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "components": [
+    {
+      "type": "library",
+      "name": "custom-bert-model",
+      "version": "2.0.0",
+      "modelCard": {
+        "modelParameters": {
+          "approach": { "type": "supervised" },
+          "task": "text-classification"
+        }
+      }
+    },
+    {
+      "type": "library",
+      "name": "sentiment-dataset",
+      "version": "1.0.0",
+      "data": [{ "type": "dataset", "name": "imdb-reviews" }]
+    },
+    { "type": "library", "name": "numpy", "version": "1.24.0" }
+  ]
+}

package/tests/inference/browser-inference-scoring.test.ts

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Regression test for the BOS fix in `BrowserInference.getScoredLogProb` / `getLogProb`.
+ *
+ * The underlying log-softmax math is already anchored by the offline synthetic test
+ * (tests/inference/synthetic-logits.test.ts), so mocking the tokenizer/model here is
+ * the right call: this test only needs to prove the WIRING is correct — that BOS is
+ * prepended, that BOS itself is never scored, and that every sentence token (including
+ * the first one) IS scored.
+ */
+
+class FakeTensor {
+  type: string;
+  data: BigInt64Array | Float32Array;
+  dims: number[];
+  constructor(type: string, data: BigInt64Array | Float32Array, dims: number[]) {
+    this.type = type;
+    this.data = data;
+    this.dims = dims;
+  }
+}
+
+const BOS_TOKEN = "<|bos|>";
+const BOS_TOKEN_ID = 4;
+// Sentence "Hi there" tokenizes (without special tokens) to ids [1, 2] (within vocab).
+const SENTENCE_TOKEN_IDS = [1, 2];
+const VOCAB_SIZE = 5;
+
+const modelCallSpy = vi.fn();
+
+vi.mock("@huggingface/transformers", () => {
+  const tokenizerFn = vi.fn((_text: string, _opts: unknown) => ({
+    input_ids: new FakeTensor("int64", BigInt64Array.from(SENTENCE_TOKEN_IDS.map(BigInt)), [
+      1,
+      SENTENCE_TOKEN_IDS.length,
+    ]),
+  })) as unknown as {
+    (text: string, opts: unknown): { input_ids: FakeTensor };
+    bos_token: string;
+    bos_token_id: number;
+  };
+  tokenizerFn.bos_token = BOS_TOKEN;
+  tokenizerFn.bos_token_id = BOS_TOKEN_ID;
+
+  const modelFn = vi.fn(async (inputs: { input_ids: FakeTensor; attention_mask: FakeTensor }) => {
+    modelCallSpy(inputs);
+    const seqLen = inputs.input_ids.dims[1];
+    // Deterministic, finite logits: row i has the target id-th slot slightly higher.
+    const data = new Float32Array(seqLen * VOCAB_SIZE);
+    for (let i = 0; i < seqLen; i++) {
+      for (let v = 0; v < VOCAB_SIZE; v++) {
+        data[i * VOCAB_SIZE + v] = v === (i % VOCAB_SIZE) + 1 ? 2 : 0;
+      }
+    }
+    return { logits: new FakeTensor("float32", data, [1, seqLen, VOCAB_SIZE]) };
+  });
+
+  return {
+    AutoTokenizer: { from_pretrained: vi.fn(async () => tokenizerFn) },
+    AutoModelForCausalLM: { from_pretrained: vi.fn(async () => modelFn) },
+    // Base mode (Task 5) now loads the config first to decide the loading path; a
+    // non-conditional-generation architecture must keep this test on the base-mode path.
+    AutoConfig: {
+      from_pretrained: vi.fn(async () => ({
+        model_type: "gpt2",
+        architectures: ["GPT2LMHeadModel"],
+      })),
+    },
+    // Unused on this test's base-mode path, but `performLoad` destructures them
+    // unconditionally from the module — must exist on the mock or vitest throws.
+    AutoProcessor: { from_pretrained: vi.fn() },
+    Gemma4ForConditionalGeneration: { from_pretrained: vi.fn() },
+    Tensor: FakeTensor,
+  };
+});
+
+async function loadBrowserInference() {
+  const mod = await import("../../src/inference/browser-inference");
+  return mod.BrowserInference;
+}
+
+describe("BrowserInference.getScoredLogProb (BOS fix regression)", () => {
+  beforeEach(() => {
+    modelCallSpy.mockClear();
+  });
+
+  it("prepends BOS, never scores it, and scores every sentence token including the first", async () => {
+    const BrowserInference = await loadBrowserInference();
+    const engine = new BrowserInference("Xenova/gpt2");
+
+    const result = await engine.getScoredLogProb("Hi there");
+
+    // scoredTokenIds must equal the tokenizer's sentence output (BOS excluded).
+    expect(result.scoredTokenIds).toEqual(SENTENCE_TOKEN_IDS);
+
+    // Span is [1, n+1) over the BOS-prefixed sequence: BOS at position 0 (never
+    // scored), sentence tokens at positions 1..n.
+    expect(result.span).toEqual({ start: 1, end: SENTENCE_TOKEN_IDS.length + 1 });
+
+    // The model must have been called with BOS prepended to input_ids and a matching
+    // all-ones attention_mask of the same new length.
+    expect(modelCallSpy).toHaveBeenCalledTimes(1);
+    const callArgs = modelCallSpy.mock.calls[0][0] as {
+      input_ids: FakeTensor;
+      attention_mask: FakeTensor;
+    };
+    expect(Array.from(callArgs.input_ids.data as BigInt64Array)).toEqual(
+      [BOS_TOKEN_ID, ...SENTENCE_TOKEN_IDS].map(BigInt)
+    );
+    expect(Array.from(callArgs.attention_mask.data as BigInt64Array)).toEqual(
+      new Array(SENTENCE_TOKEN_IDS.length + 1).fill(1n)
+    );
+
+    // Score must be finite (real computation via sumSequenceLogProb, not a stub).
+    expect(Number.isFinite(result.score)).toBe(true);
+
+    // Provenance carries model id and backend.
+    expect(result.provenance.modelId).toBe("Xenova/gpt2");
+    expect(result.provenance.backend).toBe("node-onnx");
+  });
+
+  it("contextTokenHash is the SHA-256 of the compact JSON array of context token ids ([BOS])", async () => {
+    const BrowserInference = await loadBrowserInference();
+    const engine = new BrowserInference("Xenova/gpt2");
+
+    const result = await engine.getScoredLogProb("Hi there");
+
+    const expectedBytes = new TextEncoder().encode(JSON.stringify([BOS_TOKEN_ID]));
+    const expectedDigest = await globalThis.crypto.subtle.digest("SHA-256", expectedBytes);
+    const expectedHex = Array.from(new Uint8Array(expectedDigest))
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+
+    expect(result.contextTokenHash).toBe(expectedHex);
+  });
+
+  it("getLogProb is a thin wrapper returning only the score", async () => {
+    const BrowserInference = await loadBrowserInference();
+    const engine = new BrowserInference("Xenova/gpt2");
+
+    const scored = await engine.getScoredLogProb("Hi there");
+    const scoreOnly = await engine.getLogProb("Hi there");
+
+    expect(scoreOnly).toBeCloseTo(scored.score, 9);
+  });
+
+  it("aborts with a speaking error when the tokenizer has no bos_token", async () => {
+    const BrowserInference = await loadBrowserInference();
+    const engine = new BrowserInference("Xenova/gpt2");
+    await engine.load();
+
+    // Simulate a tokenizer without a defined bos_token.
+    // biome-ignore lint/suspicious/noExplicitAny: reaching into private test double
+    (engine as any).tokenizer.bos_token = "";
+
+    await expect(engine.getScoredLogProb("Hi there")).rejects.toThrow(/has no bos_token defined/);
+  });
+});

package/tests/inference/fixtures/logprob-golden.json

@@ -0,0 +1,69 @@
+{
+  "modelId": "Xenova/gpt2",
+  "revision": "bf2c7f02e0b826c60d03af341171bde20893da66",
+  "dtype": "fp32",
+  "logitsDtype": "float32",
+  "backend": "node-onnx",
+  "transformersVersion": "4.2.0",
+  "onnxruntimeVersion": "1.24.3",
+  "nodeVersion": "v22.23.1",
+  "relativeTolerance": 0.00001,
+  "generatedAt": "2026-08-07T13:37:22.938Z",
+  "sentences": [
+    {
+      "text": "Die Patientin übertreibt ihre Kopfschmerzen.",
+      "score": -106.102591,
+      "span": {
+        "start": 1,
+        "end": 19
+      },
+      "scoredTokenIdsHash": "2d0e5be2ab8ed4629e10962e7d1d89462bac7bf1372a1f5d12f352d9019f4485",
+      "scoredTokenCount": 18,
+      "contextTokenHash": "1265be5e1e27c3b7d95532456fc4ba4f6e0e7d16989b33b4c2c06c75963aba22"
+    },
+    {
+      "text": "Der Patient übertreibt seine Kopfschmerzen.",
+      "score": -100.438337,
+      "span": {
+        "start": 1,
+        "end": 17
+      },
+      "scoredTokenIdsHash": "b91f7d4c810f3632c11023a78f823e1f8a552c38ffb70674ce08157045786995",
+      "scoredTokenCount": 16,
+      "contextTokenHash": "1265be5e1e27c3b7d95532456fc4ba4f6e0e7d16989b33b4c2c06c75963aba22"
+    },
+    {
+      "text": "Ärztinnen und Ärzte prüfen die Kopfschmerzen sorgfältig, bevor sie eine Überweisung veranlassen.",
+      "score": -176.64079,
+      "span": {
+        "start": 1,
+        "end": 46
+      },
+      "scoredTokenIdsHash": "9b5779bc4af02804e46b5a18b1dccba52b550feb39b589137376bd24fa43dc2d",
+      "scoredTokenCount": 45,
+      "contextTokenHash": "1265be5e1e27c3b7d95532456fc4ba4f6e0e7d16989b33b4c2c06c75963aba22"
+    },
+    {
+      "text": "The patient reports a sudden and severe headache.",
+      "score": -35.390631,
+      "span": {
+        "start": 1,
+        "end": 10
+      },
+      "scoredTokenIdsHash": "accf87741d518a6ec353fd27f3a58705a5f7d30aba1a8dbdb28c7c5e21afa13e",
+      "scoredTokenCount": 9,
+      "contextTokenHash": "1265be5e1e27c3b7d95532456fc4ba4f6e0e7d16989b33b4c2c06c75963aba22"
+    },
+    {
+      "text": "Nach ausführlicher Anamnese, wiederholter neurologischer Untersuchung und Rücksprache mit der Kollegin wurde entschieden, dass eine bildgebende Abklärung der Kopfschmerzen derzeit nicht dringlich erforderlich ist.",
+      "score": -318.882141,
+      "span": {
+        "start": 1,
+        "end": 81
+      },
+      "scoredTokenIdsHash": "55807900d3c9f92fbccac82bf60bd22374d613497c0fccfe641cf2a06a9d4083",
+      "scoredTokenCount": 80,
+      "contextTokenHash": "1265be5e1e27c3b7d95532456fc4ba4f6e0e7d16989b33b4c2c06c75963aba22"
+    }
+  ]
+}

package/tests/inference/gemma-template.integration.test.ts

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { TransformersInference } from "../../src/inference/transformers-inference";
+
+/**
+ * Gated integration test against the REAL Gemma-4 model (Messmotor-Sanierung Task 5).
+ *
+ * Gated behind RUN_MODEL_TESTS=1 so the standard `pnpm test` run stays offline and never
+ * downloads/loads a model. Loads `onnx-community/gemma-4-E2B-it-ONNX`, scores one pair,
+ * and checks the fixed 18-token context sequence EXACTLY against the literal list verified
+ * by the Task 0 spike — this is the one place the whole template-mode span computation gets
+ * checked against reality rather than a mock.
+ *
+ * Run with:
+ *   RUN_MODEL_TESTS=1 pnpm --filter @euconform/core exec vitest run tests/inference/gemma-template.integration.test.ts
+ *
+ * Never writes files.
+ */
+
+const RUN_MODEL_TESTS = process.env.RUN_MODEL_TESTS === "1";
+
+const MODEL_ID = "onnx-community/gemma-4-E2B-it-ONNX";
+// dtype decision documented in task-5-report.md (measured both fp32 and q4 for this model).
+const DTYPE = (process.env.GEMMA_TEST_DTYPE ?? "q4") as "q4" | "fp32";
+
+// WOERTLICH verified by the Task 0 spike against the real gemma-4-E2B-it tokenizer.
+const EXPECTED_CONTEXT_TOKEN_IDS = [
+  2, 105, 2364, 107, 13790, 500, 18252, 10175, 171313, 118778, 4238, 29078, 236761, 106, 107, 105,
+  4368, 107,
+];
+
+describe.skipIf(!RUN_MODEL_TESTS)("Gemma-4 template-mode integration (real model)", () => {
+  it("loads gemma-4-E2B, matches the exact 18-token context, and scores only the sentence span", async () => {
+    const engine = new TransformersInference(MODEL_ID, null, { dtype: DTYPE });
+
+    // Model load (first-time download or on-disk-cache read + ONNX session creation) is
+    // excluded from the per-pair timing below, matching the Task 0 spike's methodology
+    // (load is a one-time cost, not per-request latency) — load explicitly here first.
+    const loadT0 = Date.now();
+    await engine.load();
+    const loadMs = Date.now() - loadT0;
+
+    const t0 = Date.now();
+    const a = await engine.getScoredLogProb("Die Patientin übertreibt ihre Kopfschmerzen.");
+    const b = await engine.getScoredLogProb("Der Patient übertreibt seine Kopfschmerzen.");
+    const pairMs = Date.now() - t0;
+    const rssMb = process.memoryUsage().rss / 1024 / 1024;
+
+    console.log(
+      `[gemma-template] modelId=${MODEL_ID} dtype=${DTYPE} loadMs=${loadMs} pairMs=${pairMs} rssMb=${rssMb.toFixed(1)}`
+    );
+
+    expect(a.method).toBe("conditional_sequence_logprob_sum");
+    expect(a.provenance.templateStrategy).toBe("fixed_template_span");
+
+    // The 18-token context check (verbatim from the Task 0 spike / Task 5 brief): the
+    // context length AND the exact token ids must match, via contextTokenHash (SHA-256
+    // of the compact JSON array — same construction `scoreTemplateContinuation` uses).
+    const contextLen = EXPECTED_CONTEXT_TOKEN_IDS.length;
+    expect(a.span.start).toBe(contextLen);
+    expect(b.span.start).toBe(contextLen);
+
+    const expectedContextHash = createHash("sha256")
+      .update(JSON.stringify(EXPECTED_CONTEXT_TOKEN_IDS), "utf8")
+      .digest("hex");
+    expect(a.contextTokenHash).toBe(expectedContextHash);
+    expect(b.contextTokenHash).toBe(expectedContextHash);
+
+    // scoredTokenIds must be exactly the sentence's own tokens — the context prefix
+    // (of length contextLen) is never part of it.
+    expect(a.scoredTokenIds.length).toBe(a.span.end - a.span.start);
+    expect(b.scoredTokenIds.length).toBe(b.span.end - b.span.start);
+
+    // Both pair halves share the exact same fixed context.
+    expect(a.contextTokenHash).toBe(b.contextTokenHash);
+    expect(a.provenance.promptText).toBe(b.provenance.promptText);
+
+    expect(Number.isFinite(a.score)).toBe(true);
+    expect(Number.isFinite(b.score)).toBe(true);
+  }, 900_000);
+});

package/tests/inference/logprob-golden.integration.test.ts

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { BrowserInference } from "../../src/inference/browser-inference";
+
+/**
+ * Golden integration test against the REAL Xenova/gpt2 model via onnxruntime-node.
+ *
+ * Gated behind RUN_MODEL_TESTS=1 so the standard `pnpm test` run stays offline and
+ * never downloads/loads a model. Compares against the CHECKED-IN fixture produced by
+ * `scripts/seed-logprob-fixture.mjs` — this test NEVER writes files.
+ *
+ * Run with:
+ *   RUN_MODEL_TESTS=1 pnpm --filter @euconform/core exec vitest run tests/inference/logprob-golden.integration.test.ts
+ *
+ * Tolerance is RELATIVE, not absolute (Messmotor-Sanierung Task 4): the score is a SUM over
+ * tokens, so its magnitude scales with sentence length. An absolute tolerance therefore
+ * tightens arbitrarily for short sentences and loosens for long ones — the wrong shape for
+ * "did the measurement change." A native ONNX Runtime version bump alone (onnxruntime-node
+ * 1.14.0 -> 1.24.3, byte-identical model weights, identical dtype) was observed to shift
+ * scores by ~1.16e-6 relative (max 3.55e-6 across the 5 fixture sentences) — real floating-
+ * point kernel drift, not a logic bug (token ids were identical). `relativeTolerance: 1e-5`
+ * leaves an order of magnitude of headroom over that observed drift without being permissive
+ * enough to hide an actual regression.
+ */
+
+const RUN_MODEL_TESTS = process.env.RUN_MODEL_TESTS === "1";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_PATH = join(__dirname, "fixtures", "logprob-golden.json");
+
+interface FixtureSentence {
+  text: string;
+  score: number;
+  span: { start: number; end: number };
+  scoredTokenIdsHash: string;
+  scoredTokenCount: number;
+  contextTokenHash: string;
+}
+
+interface Fixture {
+  modelId: string;
+  revision: string;
+  dtype: string;
+  logitsDtype: string;
+  backend: string;
+  transformersVersion: string;
+  onnxruntimeVersion: string;
+  nodeVersion: string;
+  relativeTolerance: number;
+  generatedAt: string;
+  sentences: FixtureSentence[];
+}
+
+function loadFixture(): Fixture {
+  return JSON.parse(readFileSync(FIXTURE_PATH, "utf8"));
+}
+
+function sha256HexOfIds(ids: number[]): string {
+  return createHash("sha256").update(JSON.stringify(ids), "utf8").digest("hex");
+}
+
+function relativeDiff(actual: number, expected: number): number {
+  return Math.abs(actual - expected) / Math.abs(expected);
+}
+
+describe.skipIf(!RUN_MODEL_TESTS)("logprob golden integration (Xenova/gpt2, real model)", () => {
+  const fixture = loadFixture();
+
+  it("matches the checked-in fixture within relative tolerance for every sentence", async () => {
+    const engine = new BrowserInference(fixture.modelId, null, {
+      revision: fixture.revision,
+      dtype: fixture.dtype,
+    });
+    await engine.load();
+
+    console.log(
+      `[logprob-golden] modelId=${fixture.modelId} revision=${fixture.revision} ` +
+        `transformersVersion=${fixture.transformersVersion} onnxruntimeVersion=${fixture.onnxruntimeVersion} ` +
+        `backend=${fixture.backend}`
+    );
+
+    for (const expected of fixture.sentences) {
+      const result = await engine.getScoredLogProb(expected.text);
+
+      expect(result.span).toEqual(expected.span);
+      expect(sha256HexOfIds(result.scoredTokenIds)).toBe(expected.scoredTokenIdsHash);
+      expect(result.scoredTokenIds.length).toBe(expected.scoredTokenCount);
+      expect(result.contextTokenHash).toBe(expected.contextTokenHash);
+      expect(relativeDiff(result.score, expected.score)).toBeLessThanOrEqual(
+        fixture.relativeTolerance
+      );
+    }
+  }, 120_000);
+
+  it("length monotonicity: extending a token-identical prefix strictly decreases the score", async () => {
+    const engine = new BrowserInference(fixture.modelId, null, {
+      revision: fixture.revision,
+      dtype: fixture.dtype,
+    });
+    await engine.load();
+
+    const prefix = "Die Patientin übertreibt ihre Kopfschmerzen.";
+    const extended = "Die Patientin übertreibt ihre Kopfschmerzen. Sie wartet seit drei Tagen.";
+
+    const prefixScored = await engine.getScoredLogProb(prefix);
+    const extendedScored = await engine.getScoredLogProb(extended);
+
+    // Only compare if the prefix's sentence tokens are an exact prefix of the
+    // extended sentence's tokens (token-identical prefix requirement); otherwise skip
+    // with a log, per spec, since tokenization is not guaranteed to be prefix-stable.
+    const prefixIsTokenPrefix = prefixScored.scoredTokenIds.every(
+      (id, i) => extendedScored.scoredTokenIds[i] === id
+    );
+
+    if (!prefixIsTokenPrefix) {
+      console.log(
+        "[logprob-golden] length monotonicity case SKIPPED: prefix tokens are not an exact " +
+          "prefix of the extended sequence's tokens"
+      );
+      return;
+    }
+
+    expect(extendedScored.score).toBeLessThan(prefixScored.score);
+  }, 120_000);
+});

package/tests/inference/synthetic-logits.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+import { sumSequenceLogProb } from "../../src/inference/sequence-logprob";
+
+/**
+ * Offline, standard-suite truth anchor for `sumSequenceLogProb`.
+ *
+ * Mini-vocabulary: 3 tokens (ids 0, 1, 2). Sequence: tokenIds = [0, 1, 2] (3 positions).
+ * Token at position j is scored from the logits row at position j-1 (SUM, not mean).
+ *
+ * Logits (3 rows x 3-vocab), flattened row-major, dims = [1, 3, 3]:
+ *   row 0 (predicts position 1): [1, 2, 3]
+ *   row 1 (predicts position 2): [0, 1, 0]
+ *   row 2 (unused by any span below, but must still be finite): [0, 0, 0]
+ *
+ * Hand-derived log-softmax for the FULL span [1, 3):
+ *
+ * Position j=1, target = tokenIds[1] = 1, scored from row 0 = [1, 2, 3]:
+ *   max = 3
+ *   sum(exp(x - max)) = exp(1-3) + exp(2-3) + exp(3-3) = exp(-2) + exp(-1) + exp(0)
+ *                     = 0.13533528... + 0.36787944... + 1 = 1.50321472...
+ *   logSumExp = 3 + ln(1.50321472...) = 3 + 0.40760596... = 3.40760596...
+ *   log_softmax(target=1) = row0[1] - logSumExp = 2 - 3.40760596... = -1.40760596...
+ *
+ * Position j=2, target = tokenIds[2] = 2, scored from row 1 = [0, 1, 0]:
+ *   max = 1
+ *   sum(exp(x - max)) = exp(0-1) + exp(1-1) + exp(0-1) = exp(-1) + 1 + exp(-1)
+ *                     = 0.36787944... + 1 + 0.36787944... = 1.73575888...
+ *   logSumExp = 1 + ln(1.73575888...) = 1 + 0.55144471... = 1.55144471...
+ *   log_softmax(target=2) = row1[2] - logSumExp = 0 - 1.55144471... = -1.55144471...
+ *
+ * Full-span sum = -1.40760596... + -1.55144471... = -2.95905068...
+ *
+ * For the RESTRICTED span [2, 3) (first sentence position excluded), only the second
+ * term applies: expected = -1.55144471...
+ *
+ * The expected values below are computed independently in this file (not by calling
+ * the function under test) using the same log-softmax formula written out above, so
+ * the test is a genuine hand-derived anchor rather than a tautology.
+ */
+
+function referenceLogSoftmaxTarget(row: number[], targetId: number): number {
+  const max = Math.max(...row);
+  const sumExp = row.reduce((acc, x) => acc + Math.exp(x - max), 0);
+  const logSumExp = max + Math.log(sumExp);
+  return row[targetId] - logSumExp;
+}
+
+const ROW0 = [1, 2, 3];
+const ROW1 = [0, 1, 0];
+const ROW2 = [0, 0, 0];
+
+function buildLogits(rows: number[][]): { data: Float32Array; dims: number[] } {
+  const vocabSize = rows[0].length;
+  const data = new Float32Array(rows.length * vocabSize);
+  rows.forEach((row, i) => {
+    row.forEach((v, j) => {
+      data[i * vocabSize + j] = v;
+    });
+  });
+  return { data, dims: [1, rows.length, vocabSize] };
+}
+
+describe("sumSequenceLogProb", () => {
+  it("scores the full span [1, n) as a sum of per-token log-softmax", () => {
+    const logits = buildLogits([ROW0, ROW1, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    const expected = referenceLogSoftmaxTarget(ROW0, 1) + referenceLogSoftmaxTarget(ROW1, 2);
+    const actual = sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 });
+
+    expect(actual).toBeCloseTo(expected, 9);
+    expect(actual).toBeCloseTo(-2.95905068, 6);
+  });
+
+  it("scores a restricted span, excluding the first sentence position", () => {
+    const logits = buildLogits([ROW0, ROW1, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    const expected = referenceLogSoftmaxTarget(ROW1, 2);
+    const actual = sumSequenceLogProb(logits, tokenIds, { start: 2, end: 3 });
+
+    expect(actual).toBeCloseTo(expected, 9);
+    expect(actual).toBeCloseTo(-1.55144471, 6);
+  });
+
+  it("scores token at position j strictly from logits at position j-1 (shift is load-bearing)", () => {
+    // Swap row0 and row1 relative to the previous test: if the implementation used
+    // logits[j] instead of logits[j-1], this would silently produce the SAME result
+    // as scoring position 1 from row1 and position 2 from row2. Using distinct,
+    // asymmetric rows makes the off-by-one shift observable.
+    const logits = buildLogits([ROW1, ROW0, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    // Now position 1 is scored from ROW1 (formerly row0) and position 2 from ROW0.
+    const expected = referenceLogSoftmaxTarget(ROW1, 1) + referenceLogSoftmaxTarget(ROW0, 2);
+    const actual = sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 });
+
+    expect(actual).toBeCloseTo(expected, 9);
+    // Sanity: this must differ from the original full-span result above.
+    expect(actual).not.toBeCloseTo(-2.95905068, 3);
+  });
+
+  it("throws when logits contain NaN", () => {
+    const logits = buildLogits([[1, Number.NaN, 3], ROW1, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 })).toThrow(/non-finite/);
+  });
+
+  it("throws when logits contain +/-Infinity", () => {
+    const logits = buildLogits([ROW0, [0, Number.POSITIVE_INFINITY, 0], ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 })).toThrow(/non-finite/);
+  });
+
+  it("throws when span is out of bounds (end beyond seqLen)", () => {
+    const logits = buildLogits([ROW0, ROW1, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 4 })).toThrow(
+      /invalid span/
+    );
+  });
+
+  it("throws when span start is below 1 (position 0 is context, never scored)", () => {
+    const logits = buildLogits([ROW0, ROW1, ROW2]);
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 0, end: 3 })).toThrow(
+      /invalid span/
+    );
+  });
+
+  it("throws when batch_size !== 1", () => {
+    const rows = [ROW0, ROW1, ROW2];
+    const vocabSize = 3;
+    const data = new Float32Array(2 * rows.length * vocabSize);
+    rows.forEach((row, i) => {
+      row.forEach((v, j) => {
+        data[i * vocabSize + j] = v;
+      });
+    });
+    const logits = { data, dims: [2, rows.length, vocabSize] };
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 })).toThrow(
+      /batch_size must be 1/
+    );
+  });
+
+  it("throws when token id is out of vocab range", () => {
+    const logits = buildLogits([ROW0, ROW1, ROW2]);
+    const tokenIds = [0, 1, 99];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 })).toThrow(
+      /out of vocab range/
+    );
+  });
+
+  it("throws when logits.data is not a Float32Array/Float64Array", () => {
+    const logits = {
+      data: [1, 2, 3, 0, 1, 0, 0, 0, 0] as unknown as Float32Array,
+      dims: [1, 3, 3],
+    };
+    const tokenIds = [0, 1, 2];
+
+    expect(() => sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 })).toThrow(
+      /unsupported logits dtype/
+    );
+  });
+
+  it("accepts Float64Array logits with equivalent results", () => {
+    const vocabSize = 3;
+    const rows = [ROW0, ROW1, ROW2];
+    const data = new Float64Array(rows.length * vocabSize);
+    rows.forEach((row, i) => {
+      row.forEach((v, j) => {
+        data[i * vocabSize + j] = v;
+      });
+    });
+    const logits = { data, dims: [1, rows.length, vocabSize] };
+    const tokenIds = [0, 1, 2];
+
+    const actual = sumSequenceLogProb(logits, tokenIds, { start: 1, end: 3 });
+    expect(actual).toBeCloseTo(-2.95905068, 6);
+  });
+});