effect-gpt 0.1.0

package/tests/ts/llm_parameters.test.ts

@@ -0,0 +1,96 @@
+import { describe, test, expect } from "bun:test"
+import { LLM } from "../../src/model/LLM"
+import { Vocab } from "../../src/vocab/Vocab"
+import { EMBEDDING_DIM, HIDDEN_DIM, MAX_SEQ_LEN } from "../../src/config"
+import { makeLLM } from "./support/factories"
+import { seeded } from "../../src/tensor/random"
+
+describe("LLM Parameters", () => {
+  const computeExpectedParams = (vocabSize: number, numTransformerBlocks: number): number => {
+    const embeddingsParams = vocabSize * EMBEDDING_DIM + MAX_SEQ_LEN * EMBEDDING_DIM
+
+    const selfAttentionParams = 3 * EMBEDDING_DIM * EMBEDDING_DIM
+    const feedForwardParams =
+      EMBEDDING_DIM * HIDDEN_DIM + HIDDEN_DIM + HIDDEN_DIM * EMBEDDING_DIM + EMBEDDING_DIM
+    const layerNormParams = 2 * (2 * EMBEDDING_DIM)
+    const transformerBlockParams = selfAttentionParams + feedForwardParams + layerNormParams
+
+    const outputProjectionParams = EMBEDDING_DIM * vocabSize + vocabSize
+
+    return embeddingsParams + numTransformerBlocks * transformerBlockParams + outputProjectionParams
+  }
+
+  test("default LLM parameter count matches formula", () => {
+    const llm = LLM.default(seeded(1))
+    const vocabSize = llm.vocab.words.length
+    const expected = computeExpectedParams(vocabSize, 1)
+    expect(llm.totalParameters()).toBe(expected)
+  })
+
+  test("make LLM parameter count matches formula (3 transformer blocks)", () => {
+    const vocab = Vocab.make(Vocab.defaultWords())
+    const llm = LLM.make(vocab, seeded(2))
+    const vocabSize = vocab.words.length
+    const expected = computeExpectedParams(vocabSize, 3)
+    expect(llm.totalParameters()).toBe(expected)
+  })
+
+  test("factory LLM with 1 block matches formula", () => {
+    const vocabWords = Vocab.defaultWords()
+    const llm = makeLLM({ vocabWords, numTransformerBlocks: 1 })
+    const expected = computeExpectedParams(vocabWords.length, 1)
+    expect(llm.totalParameters()).toBe(expected)
+  })
+
+  test("factory LLM with 2 blocks matches formula", () => {
+    const vocabWords = Vocab.defaultWords()
+    const llm = makeLLM({ vocabWords, numTransformerBlocks: 2 })
+    const expected = computeExpectedParams(vocabWords.length, 2)
+    expect(llm.totalParameters()).toBe(expected)
+  })
+
+  test("individual layer params sum to total", () => {
+    const llm = LLM.default(seeded(3))
+    const sumOfLayers = llm.network.reduce((sum, layer) => sum + layer.parametersCount, 0)
+    expect(llm.totalParameters()).toBe(sumOfLayers)
+  })
+
+  test("larger vocab increases parameter count", () => {
+    const smallVocab = ["a", "b", "</s>"]
+    const largeVocab = ["a", "b", "c", "d", "e", "f", "g", "h", "</s>"]
+
+    const smallLLM = makeLLM({ vocabWords: smallVocab, numTransformerBlocks: 1 })
+    const largeLLM = makeLLM({ vocabWords: largeVocab, numTransformerBlocks: 1 })
+
+    expect(largeLLM.totalParameters()).toBeGreaterThan(smallLLM.totalParameters())
+  })
+
+  test("more transformer blocks increases parameter count", () => {
+    const vocabWords = Vocab.defaultWords()
+    const llm1Block = makeLLM({ vocabWords, numTransformerBlocks: 1 })
+    const llm3Blocks = makeLLM({ vocabWords, numTransformerBlocks: 3 })
+
+    expect(llm3Blocks.totalParameters()).toBeGreaterThan(llm1Block.totalParameters())
+  })
+
+  test("parameter count formula components", () => {
+    const vocabSize = 6
+    const numBlocks = 1
+
+    const embeddingsParams = vocabSize * EMBEDDING_DIM + MAX_SEQ_LEN * EMBEDDING_DIM
+    expect(embeddingsParams).toBe(6 * 128 + 80 * 128)
+
+    const selfAttentionParams = 3 * EMBEDDING_DIM * EMBEDDING_DIM
+    expect(selfAttentionParams).toBe(3 * 128 * 128)
+
+    const feedForwardParams =
+      EMBEDDING_DIM * HIDDEN_DIM + HIDDEN_DIM + HIDDEN_DIM * EMBEDDING_DIM + EMBEDDING_DIM
+    expect(feedForwardParams).toBe(128 * 256 + 256 + 256 * 128 + 128)
+
+    const layerNormParams = 2 * (2 * EMBEDDING_DIM)
+    expect(layerNormParams).toBe(2 * (2 * 128))
+
+    const outputProjectionParams = EMBEDDING_DIM * vocabSize + vocabSize
+    expect(outputProjectionParams).toBe(128 * 6 + 6)
+  })
+})

package/tests/ts/llm_predict.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from "bun:test"
+import * as Option from "effect/Option"
+import { runEffect } from "./support/runEffect"
+import { makeLLM, makeLLMWithNetwork, makeEmbeddings, makeTransformerBlock } from "./support/factories"
+import { StubOutputProjection } from "./support/stubs"
+import { Vocab } from "../../src/vocab/Vocab"
+import { CANONICAL_SEED } from "./support/seed"
+
+describe("LLM Predict", () => {
+  const vocabWords = Vocab.defaultWords()
+  const eosTokenId = vocabWords.indexOf("</s>")
+
+  test("predict stops at EOS token", () => {
+    const vocab = Vocab.make(vocabWords)
+    const stubOutput = new StubOutputProjection(vocabWords.length, eosTokenId, 2)
+
+    const llm = makeLLMWithNetwork({
+      vocabWords,
+      network: [
+        makeEmbeddings(vocabWords.length, { seed: CANONICAL_SEED }),
+        makeTransformerBlock({ seed: CANONICAL_SEED }),
+        stubOutput
+      ]
+    })
+
+    const result = runEffect(llm.predict("hello"))
+    expect(result).toContain("</s>")
+  })
+
+  test("predict output token count respects EOS", () => {
+    const stubOutput = new StubOutputProjection(vocabWords.length, eosTokenId, 3)
+
+    const llm = makeLLMWithNetwork({
+      vocabWords,
+      network: [
+        makeEmbeddings(vocabWords.length, { seed: CANONICAL_SEED }),
+        makeTransformerBlock({ seed: CANONICAL_SEED }),
+        stubOutput
+      ]
+    })
+
+    const tokens = runEffect(llm.forward("hello"))
+    expect(tokens.length).toBeLessThanOrEqual(3)
+  })
+
+  test("predict decodes tokens correctly", () => {
+    const stubOutput = new StubOutputProjection(vocabWords.length, eosTokenId, 1)
+
+    const llm = makeLLMWithNetwork({
+      vocabWords,
+      network: [
+        makeEmbeddings(vocabWords.length, { seed: CANONICAL_SEED }),
+        makeTransformerBlock({ seed: CANONICAL_SEED }),
+        stubOutput
+      ]
+    })
+
+    const tokens = runEffect(llm.forward("hello"))
+    for (const tokenId of tokens) {
+      const decoded = llm.vocab.decode(tokenId)
+      expect(Option.isSome(decoded)).toBe(true)
+    }
+  })
+
+  test("predict with empty input returns empty string", () => {
+    const llm = makeLLM({ vocabWords })
+    const result = runEffect(llm.predict(""))
+    expect(result).toBe("")
+  })
+
+  test("forward with empty input returns empty tokens", () => {
+    const llm = makeLLM({ vocabWords })
+    const tokens = runEffect(llm.forward(""))
+    expect(tokens.length).toBe(0)
+  })
+
+  test("predict with seeded RNG is deterministic", () => {
+    const createLLM = () => {
+      const stubOutput = new StubOutputProjection(vocabWords.length, eosTokenId, 2)
+      return makeLLMWithNetwork({
+        vocabWords,
+        network: [
+          makeEmbeddings(vocabWords.length, { seed: CANONICAL_SEED }),
+          makeTransformerBlock({ seed: CANONICAL_SEED }),
+          stubOutput
+        ]
+      })
+    }
+
+    const llm1 = createLLM()
+    const llm2 = createLLM()
+
+    const result1 = runEffect(llm1.predict("hello"))
+    const result2 = runEffect(llm2.predict("hello"))
+
+    expect(result1).toBe(result2)
+  })
+})

package/tests/ts/llm_tokenize.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test"
+import { Vocab } from "../../src/vocab/Vocab"
+import { tokenize } from "../../src/tokenize/tokenize"
+import * as Option from "effect/Option"
+
+describe("LLM Tokenize", () => {
+  const vocab = Vocab.make(Vocab.defaultWords())
+
+  test("encode single word", () => {
+    const tokens = tokenize("hello", vocab)
+    expect(tokens.length).toBe(1)
+    expect(tokens[0]).toBe(Option.getOrThrow(vocab.encode("hello")))
+  })
+
+  test("encode multiple words", () => {
+    const tokens = tokenize("hello world", vocab)
+    expect(tokens.length).toBe(2)
+    expect(tokens[0]).toBe(Option.getOrThrow(vocab.encode("hello")))
+    expect(tokens[1]).toBe(Option.getOrThrow(vocab.encode("world")))
+  })
+
+  test("</s> token encodes correctly", () => {
+    const eosId = vocab.encode("</s>")
+    expect(Option.isSome(eosId)).toBe(true)
+    const tokens = tokenize("</s>", vocab)
+    expect(tokens.length).toBe(1)
+    expect(tokens[0]).toBe(Option.getOrThrow(eosId))
+  })
+
+  test("decode returns original word", () => {
+    const tokens = tokenize("hello", vocab)
+    const decoded = vocab.decode(tokens[0]!)
+    expect(Option.isSome(decoded)).toBe(true)
+    expect(Option.getOrThrow(decoded)).toBe("hello")
+  })
+
+  test("roundtrip encode/decode for all default words", () => {
+    const words = Vocab.defaultWords()
+    for (const word of words) {
+      const tokens = tokenize(word, vocab)
+      expect(tokens.length).toBeGreaterThanOrEqual(1)
+      const decoded = vocab.decode(tokens[0]!)
+      expect(Option.isSome(decoded)).toBe(true)
+    }
+  })
+
+  test("sentence with </s> appended encodes correctly", () => {
+    const tokens = tokenize("hello world </s>", vocab)
+    expect(tokens.length).toBe(3)
+    const lastToken = tokens[tokens.length - 1]!
+    const eosId = Option.getOrThrow(vocab.encode("</s>"))
+    expect(lastToken).toBe(eosId)
+  })
+
+  test("empty string returns empty tokens", () => {
+    const tokens = tokenize("", vocab)
+    expect(tokens.length).toBe(0)
+  })
+
+  test("unknown word returns empty for that word", () => {
+    const tokens = tokenize("unknownxyz", vocab)
+    expect(tokens.length).toBe(0)
+  })
+
+  test("multiple spaces handled correctly", () => {
+    const tokens = tokenize("hello   world", vocab)
+    expect(tokens.length).toBe(2)
+  })
+})

package/tests/ts/output_projection.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from "bun:test"
+import { runEffect } from "./support/runEffect"
+import { expectShape, expectNotClose, expectFinite } from "./support/tensorMatchers"
+import { makeOutputProjection } from "./support/factories"
+import * as T from "../../src/tensor/Tensor2D"
+import { EMBEDDING_DIM } from "../../src/config"
+
+describe("OutputProjection", () => {
+  const vocabSize = 10
+
+  test("weight dimensions [EMBEDDING_DIM, vocabSize]", () => {
+    const proj = makeOutputProjection(vocabSize)
+    expectShape(proj.wOut, [EMBEDDING_DIM, vocabSize])
+  })
+
+  test("bias dimensions [1, vocabSize]", () => {
+    const proj = makeOutputProjection(vocabSize)
+    expectShape(proj.bOut, [1, vocabSize])
+  })
+
+  test("forward [seqLen, dim] → [seqLen, vocabSize]", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const input = T.ones(3, EMBEDDING_DIM)
+    const output = runEffect(proj.forward(input))
+    expectShape(output, [3, vocabSize])
+  })
+
+  test("forward across sequence lengths", () => {
+    const proj = makeOutputProjection(vocabSize)
+    for (let seqLen = 1; seqLen <= 4; seqLen++) {
+      const input = T.ones(seqLen, EMBEDDING_DIM)
+      const output = runEffect(proj.forward(input))
+      expectShape(output, [seqLen, vocabSize])
+    }
+  })
+
+  test("output contains finite values", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const input = T.ones(3, EMBEDDING_DIM)
+    const output = runEffect(proj.forward(input))
+    expectFinite(output)
+  })
+
+  test("backward gradient shape [seqLen, EMBEDDING_DIM]", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const input = T.ones(3, EMBEDDING_DIM)
+    runEffect(proj.forward(input))
+    const dOut = T.ones(3, vocabSize)
+    const grad = runEffect(proj.backward(dOut, 0.01))
+    expectShape(grad, [3, EMBEDDING_DIM])
+  })
+
+  test("backward updates wOut", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const wOutBefore = T.clone(proj.wOut)
+    const input = T.ones(3, EMBEDDING_DIM)
+    runEffect(proj.forward(input))
+    const dOut = T.ones(3, vocabSize)
+    runEffect(proj.backward(dOut, 0.01))
+    expectNotClose(proj.wOut, wOutBefore)
+  })
+
+  test("backward updates bOut", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const bOutBefore = T.clone(proj.bOut)
+    const input = T.ones(3, EMBEDDING_DIM)
+    runEffect(proj.forward(input))
+    const dOut = T.ones(3, vocabSize)
+    runEffect(proj.backward(dOut, 0.01))
+    expectNotClose(proj.bOut, bOutBefore)
+  })
+
+  test("parametersCount", () => {
+    const proj = makeOutputProjection(vocabSize)
+    const expected = EMBEDDING_DIM * vocabSize + vocabSize
+    expect(proj.parametersCount).toBe(expected)
+  })
+})

package/tests/ts/random.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "bun:test"
+import { seeded } from "../../src/tensor/random"
+import { testRng, CANONICAL_SEED } from "./support/seed"
+
+describe("Rng", () => {
+  it("produces deterministic sequence with same seed", () => {
+    const rng1 = seeded(42)
+    const rng2 = seeded(42)
+
+    const seq1 = Array.from({ length: 10 }, () => rng1.next())
+    const seq2 = Array.from({ length: 10 }, () => rng2.next())
+
+    expect(seq1).toEqual(seq2)
+  })
+
+  it("produces different sequences with different seeds", () => {
+    const rng1 = seeded(42)
+    const rng2 = seeded(43)
+
+    const seq1 = Array.from({ length: 10 }, () => rng1.next())
+    const seq2 = Array.from({ length: 10 }, () => rng2.next())
+
+    expect(seq1).not.toEqual(seq2)
+  })
+
+  it("values are in [0, 1) range", () => {
+    const rng = testRng()
+    for (let i = 0; i < 1000; i++) {
+      const val = rng.next()
+      expect(val).toBeGreaterThanOrEqual(0)
+      expect(val).toBeLessThan(1)
+    }
+  })
+
+  it("testRng uses canonical seed", () => {
+    const rng1 = testRng()
+    const rng2 = seeded(CANONICAL_SEED)
+
+    const seq1 = Array.from({ length: 5 }, () => rng1.next())
+    const seq2 = Array.from({ length: 5 }, () => rng2.next())
+
+    expect(seq1).toEqual(seq2)
+  })
+})

package/tests/ts/self_attention.test.ts

@@ -0,0 +1,63 @@
+import { describe, test, expect } from "bun:test"
+import { runEffect } from "./support/runEffect"
+import { expectShape, expectNotClose, expectFinite } from "./support/tensorMatchers"
+import { makeSelfAttention } from "./support/factories"
+import * as T from "../../src/tensor/Tensor2D"
+import { EMBEDDING_DIM } from "../../src/config"
+
+describe("SelfAttention", () => {
+  test("forward shape matches input", () => {
+    const attention = makeSelfAttention()
+    const input = T.ones(3, EMBEDDING_DIM)
+    const output = runEffect(attention.forward(input))
+    expectShape(output, [3, EMBEDDING_DIM])
+  })
+
+  test("shape across sequence lengths 1..5", () => {
+    const attention = makeSelfAttention()
+    for (let seqLen = 1; seqLen <= 4; seqLen++) {
+      const input = T.ones(seqLen, EMBEDDING_DIM)
+      const output = runEffect(attention.forward(input))
+      expectShape(output, [seqLen, EMBEDDING_DIM])
+    }
+  })
+
+  test("output contains finite values", () => {
+    const attention = makeSelfAttention()
+    const input = T.ones(3, EMBEDDING_DIM)
+    const output = runEffect(attention.forward(input))
+    expectFinite(output)
+  })
+
+  test("backward returns correct shape", () => {
+    const attention = makeSelfAttention()
+    const seqLen = 3
+    const input = T.ones(seqLen, EMBEDDING_DIM)
+    runEffect(attention.forward(input))
+    const gradOut = T.ones(seqLen, EMBEDDING_DIM)
+    const grad = runEffect(attention.backward(gradOut, 0.01))
+    expectShape(grad, [seqLen, EMBEDDING_DIM])
+  })
+
+  test("backward updates wQ/wK/wV weights", () => {
+    const attention = makeSelfAttention()
+    const wQBefore = T.clone(attention.wQ)
+    const wKBefore = T.clone(attention.wK)
+    const wVBefore = T.clone(attention.wV)
+
+    const input = T.ones(3, EMBEDDING_DIM)
+    runEffect(attention.forward(input))
+    const gradOut = T.ones(3, EMBEDDING_DIM)
+    runEffect(attention.backward(gradOut, 0.01))
+
+    expectNotClose(attention.wQ, wQBefore)
+    expectNotClose(attention.wK, wKBefore)
+    expectNotClose(attention.wV, wVBefore)
+  })
+
+  test("parametersCount", () => {
+    const attention = makeSelfAttention()
+    const expectedCount = 3 * EMBEDDING_DIM * EMBEDDING_DIM
+    expect(attention.parametersCount).toBe(expectedCount)
+  })
+})

package/tests/ts/support/factories.ts

@@ -0,0 +1,126 @@
+/**
+ * Seeded model factories for reproducible tests.
+ * All factories accept optional seed to produce deterministic weights.
+ */
+import { seeded, type Rng } from "../../../src/tensor/random"
+import { CANONICAL_SEED } from "./seed"
+import { EMBEDDING_DIM, HIDDEN_DIM, MAX_SEQ_LEN } from "../../../src/config"
+import { Embeddings } from "../../../src/model/Embeddings"
+import { SelfAttention } from "../../../src/model/SelfAttention"
+import { FeedForward } from "../../../src/model/FeedForward"
+import { LayerNorm } from "../../../src/model/LayerNorm"
+import { TransformerBlock } from "../../../src/model/TransformerBlock"
+import { OutputProjection } from "../../../src/model/OutputProjection"
+import { LLM } from "../../../src/model/LLM"
+import { Vocab } from "../../../src/vocab/Vocab"
+import type { ModelLayer } from "../../../src/model/ModelLayer"
+
+interface EmbeddingsOptions {
+  seed?: number
+  embeddingDim?: number
+  maxSeqLen?: number
+}
+
+export const makeEmbeddings = (vocabSize: number, options: EmbeddingsOptions = {}): Embeddings => {
+  const { seed = CANONICAL_SEED, embeddingDim = EMBEDDING_DIM, maxSeqLen = MAX_SEQ_LEN } = options
+  const rng = seeded(seed)
+  return new Embeddings(vocabSize, embeddingDim, maxSeqLen, rng)
+}
+
+interface SelfAttentionOptions {
+  seed?: number
+  embeddingDim?: number
+}
+
+export const makeSelfAttention = (options: SelfAttentionOptions = {}): SelfAttention => {
+  const { seed = CANONICAL_SEED, embeddingDim = EMBEDDING_DIM } = options
+  const rng = seeded(seed)
+  return new SelfAttention(embeddingDim, rng)
+}
+
+interface FeedForwardOptions {
+  seed?: number
+  embeddingDim?: number
+  hiddenDim?: number
+}
+
+export const makeFeedForward = (options: FeedForwardOptions = {}): FeedForward => {
+  const { seed = CANONICAL_SEED, embeddingDim = EMBEDDING_DIM, hiddenDim = HIDDEN_DIM } = options
+  const rng = seeded(seed)
+  return new FeedForward(embeddingDim, hiddenDim, rng)
+}
+
+interface LayerNormOptions {
+  embeddingDim?: number
+}
+
+export const makeLayerNorm = (options: LayerNormOptions = {}): LayerNorm => {
+  const { embeddingDim = EMBEDDING_DIM } = options
+  return new LayerNorm(embeddingDim)
+}
+
+interface TransformerBlockOptions {
+  seed?: number
+  embeddingDim?: number
+  hiddenDim?: number
+}
+
+export const makeTransformerBlock = (options: TransformerBlockOptions = {}): TransformerBlock => {
+  const { seed = CANONICAL_SEED, embeddingDim = EMBEDDING_DIM, hiddenDim = HIDDEN_DIM } = options
+  const rng = seeded(seed)
+  return new TransformerBlock(embeddingDim, hiddenDim, rng)
+}
+
+interface OutputProjectionOptions {
+  seed?: number
+  embeddingDim?: number
+}
+
+export const makeOutputProjection = (
+  vocabSize: number,
+  options: OutputProjectionOptions = {}
+): OutputProjection => {
+  const { seed = CANONICAL_SEED, embeddingDim = EMBEDDING_DIM } = options
+  const rng = seeded(seed)
+  return new OutputProjection(embeddingDim, vocabSize, rng)
+}
+
+/**
+ * Creates a fresh RNG instance for custom use in tests.
+ */
+export const makeRng = (seed: number = CANONICAL_SEED): Rng => seeded(seed)
+
+interface LLMOptions {
+  seed?: number
+  vocabWords?: ReadonlyArray<string>
+  numTransformerBlocks?: number
+}
+
+export const makeLLM = (options: LLMOptions = {}): LLM => {
+  const {
+    seed = CANONICAL_SEED,
+    vocabWords = Vocab.defaultWords(),
+    numTransformerBlocks = 1
+  } = options
+  const vocab = Vocab.make(vocabWords)
+  const rng = seeded(seed)
+  const network: Array<ModelLayer> = [new Embeddings(vocab.words.length, EMBEDDING_DIM, MAX_SEQ_LEN, rng)]
+
+  for (let i = 0; i < numTransformerBlocks; i++) {
+    network.push(new TransformerBlock(EMBEDDING_DIM, HIDDEN_DIM, rng))
+  }
+
+  network.push(new OutputProjection(EMBEDDING_DIM, vocab.words.length, rng))
+  return new LLM(vocab, network)
+}
+
+interface LLMWithCustomNetworkOptions {
+  vocabWords?: ReadonlyArray<string>
+  network: ReadonlyArray<ModelLayer>
+}
+
+export const makeLLMWithNetwork = (options: LLMWithCustomNetworkOptions): LLM => {
+  const { vocabWords = Vocab.defaultWords(), network } = options
+  const vocab = Vocab.make(vocabWords)
+  return new LLM(vocab, network)
+}

package/tests/ts/support/runEffect.ts

@@ -0,0 +1,29 @@
+/**
+ * Helpers for running Effect programs in Bun tests.
+ */
+import * as Effect from "effect/Effect"
+
+/**
+ * Runs an Effect synchronously and returns the result.
+ * Throws if the effect fails or requires async execution.
+ * Use for pure, synchronous effects in tests.
+ */
+export const runEffect = <A, E>(effect: Effect.Effect<A, E>): A => Effect.runSync(effect)
+
+
+
+/**
+ * Runs an Effect and expects it to fail with a specific error type.
+ * Returns the error for further assertions.
+ */
+export const runEffectFail = <A, E>(effect: Effect.Effect<A, E>): E => {
+  const result = Effect.runSyncExit(effect)
+  if (result._tag === "Failure") {
+    const cause = result.cause
+    if (cause._tag === "Fail") {
+      return cause.error
+    }
+    throw new Error(`Effect failed with unexpected cause: ${cause._tag}`)
+  }
+  throw new Error("Expected Effect to fail, but it succeeded")
+}

package/tests/ts/support/seed.ts

@@ -0,0 +1,12 @@
+/**
+ * Test helper to create seeded RNG with canonical test seed.
+ */
+import { seeded, type Rng } from "../../../src/tensor/random"
+
+/** Canonical seed for deterministic tests (matches Rust convention). */
+export const CANONICAL_SEED = 1337
+
+/** Creates a seeded RNG with the canonical test seed. */
+export const testRng = (): Rng => seeded(CANONICAL_SEED)
+
+

package/tests/ts/support/stubs.ts

@@ -0,0 +1,58 @@
+/**
+ * Stub implementations for integration testing.
+ */
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type { Tensor2D } from "../../../src/tensor/Tensor2D"
+import * as T from "../../../src/tensor/Tensor2D"
+import type { ShapeError } from "../../../src/tensor/ops"
+import type { ModelLayer } from "../../../src/model/ModelLayer"
+import { SilentLoggerLive } from "../../../src/services/Logger"
+import { NoOpMetricsLive } from "../../../src/services/Metrics"
+
+/**
+ * Stub OutputProjection that forces EOS token after N forward calls.
+ * Used to test prediction loop termination.
+ */
+export class StubOutputProjection implements ModelLayer {
+  readonly _tag = "OutputProjection" as const
+  private callCount = 0
+  private readonly eosAfter: number
+  private readonly eosTokenId: number
+  private readonly vocabSize: number
+
+  constructor(vocabSize: number, eosTokenId: number, eosAfter: number) {
+    this.vocabSize = vocabSize
+    this.eosTokenId = eosTokenId
+    this.eosAfter = eosAfter
+  }
+
+  get parametersCount(): number {
+    return 0
+  }
+
+  forward(input: Tensor2D): Effect.Effect<Tensor2D, ShapeError> {
+    return Effect.sync(() => {
+      this.callCount++
+      const logits = T.zeros(input.rows, this.vocabSize)
+      const targetToken = this.callCount >= this.eosAfter ? this.eosTokenId : 0
+      const lastRowStart = (input.rows - 1) * this.vocabSize
+      logits.data[lastRowStart + targetToken] = 100.0
+      return logits
+    })
+  }
+
+  backward(_dOut: Tensor2D, _lr: number): Effect.Effect<Tensor2D, ShapeError> {
+    return Effect.succeed(T.zeros(1, 1))
+  }
+
+  resetCallCount(): void {
+    this.callCount = 0
+  }
+}
+
+/**
+ * Shared test services layer with silent logging and no-op metrics.
+ * Use this in tests to suppress log output and avoid metrics overhead.
+ */
+export const TestServicesLayer = Layer.mergeAll(SilentLoggerLive, NoOpMetricsLive)