@effect-uai/core 0.2.0 → 0.4.0

package/src/speech-synthesizer/SpeechSynthesizer.ts

@@ -0,0 +1,131 @@
+import { Context, Effect, Function, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
+
+/**
+ * Cross-provider synthesis request. Provider-specific extensions
+ * (ElevenLabs `stability` / `similarity_boost`, Cartesia `emotion`,
+ * MiniMax `vol` / `pitch`, Azure SSML style tags) live on each
+ * provider's typed request which extends this and narrows `model` and
+ * `voiceId`.
+ */
+export type CommonSynthesizeRequest = {
+  readonly text: string
+  /** Model identifier. Each provider narrows. */
+  readonly model: string
+  /**
+   * Voice identifier. Per-provider request types narrow this to a
+   * typed literal union of stock voices + `(string & {})` escape for
+   * custom cloned voice IDs. Providers without custom-voice support
+   * (OpenAI, Deepgram Aura, AWS Polly) narrow to the stock-only union.
+   */
+  readonly voiceId: string
+  readonly outputFormat?: AudioFormat
+  readonly speed?: number
+  readonly languageCode?: string
+}
+
+/**
+ * Incremental-synthesis request — text arrives as `Stream<string>`.
+ * Gated by the `TtsIncrementalText` capability marker; only providers
+ * that ship the marker can be used.
+ *
+ * Multi-context features (Cartesia `context_id`, ElevenLabs `multi-
+ * stream-input`) are NOT exposed here — one logical utterance per
+ * call. Provider extensions can expose `forkContext` for that.
+ */
+export type CommonStreamSynthesizeRequest = Omit<CommonSynthesizeRequest, "text">
+
+export type SpeechSynthesizerService = {
+  /** One-shot. Full text in, full audio bytes out. Universally supported. */
+  readonly synthesize: (
+    request: CommonSynthesizeRequest,
+  ) => Effect.Effect<AudioBlob, AiError.AiError>
+  /**
+   * Full text in, audio chunks streamed out (chunked HTTP). Universally
+   * supported across providers that offer any streaming TTS at all.
+   */
+  readonly streamSynthesis: (
+    request: CommonSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  /**
+   * Incremental text in (as a Stream), audio chunks streamed out. The
+   * underlying WS connection is acquired on first pull and released
+   * when the output stream is finalized via `Stream.scoped`.
+   *
+   * Gated by the `TtsIncrementalText` capability marker on the top-
+   * level helper — providers without WS-style incremental input don't
+   * ship the marker, so calls fail at `Effect.provide` with a type
+   * error.
+   */
+  readonly streamSynthesisFrom: <E, R>(
+    textIn: Stream.Stream<string, E, R>,
+    request: CommonStreamSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+}
+
+export class SpeechSynthesizer extends Context.Service<
+  SpeechSynthesizer,
+  SpeechSynthesizerService
+>()("@betalyra/effect-uai/SpeechSynthesizer") {}
+
+/**
+ * Capability marker — provided by provider layers whose
+ * `streamSynthesisFrom` is wired up at the wire level. OpenAI, Azure
+ * (wire), and AWS Polly non-Generative do not ship it. Calling
+ * `streamSynthesisFrom` while only one of those Layers is in scope
+ * fails at `Effect.provide` with a type error.
+ *
+ * Phantom — the value is `void`; providers register with
+ * `Layer.succeed(TtsIncrementalText, undefined)`.
+ */
+export class TtsIncrementalText extends Context.Service<TtsIncrementalText, void>()(
+  "@betalyra/effect-uai/capability/TtsIncrementalText",
+) {}
+
+/** One-shot synthesis. */
+export const synthesize = (
+  request: CommonSynthesizeRequest,
+): Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer> =>
+  Effect.flatMap(SpeechSynthesizer.asEffect(), (s) => s.synthesize(request))
+
+/** Full text in, audio chunks out. */
+export const streamSynthesis = (
+  request: CommonSynthesizeRequest,
+): Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer> =>
+  Stream.unwrap(Effect.map(SpeechSynthesizer.asEffect(), (s) => s.streamSynthesis(request)))
+
+/**
+ * Incremental synthesis. Dual-arity: pipeable (data-last) and direct
+ * (data-first). Requires `TtsIncrementalText` in R — providers without
+ * incremental-text-in support are a type error at provide time.
+ *
+ * @example
+ * ```ts
+ * const audio = LanguageModel.streamTurn(turnReq).pipe(
+ *   Stream.filterMap(Turn.toTextDelta),
+ *   SpeechSynthesizer.streamSynthesisFrom(synthReq),
+ * )
+ * ```
+ */
+export const streamSynthesisFrom: {
+  (
+    request: CommonStreamSynthesizeRequest,
+  ): <E, R>(
+    textIn: Stream.Stream<string, E, R>,
+  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R | SpeechSynthesizer | TtsIncrementalText>
+  <E, R>(
+    textIn: Stream.Stream<string, E, R>,
+    request: CommonStreamSynthesizeRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError | E, R | SpeechSynthesizer | TtsIncrementalText>
+} = Function.dual(
+  2,
+  <E, R>(textIn: Stream.Stream<string, E, R>, request: CommonStreamSynthesizeRequest) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const s = yield* SpeechSynthesizer.asEffect()
+        yield* TtsIncrementalText.asEffect()
+        return s.streamSynthesisFrom(textIn, request)
+      }),
+    ),
+)

package/src/streaming/JSONL.ts

@@ -79,6 +79,18 @@ export const parse =
       ),
     )
 
+/**
+ * Best-effort parse of a single JSON frame. Returns the parsed value or
+ * `undefined` on malformed input. Realtime WS adapters use this to skip
+ * non-JSON or partially-received frames silently rather than fail the
+ * entire session over one bad frame.
+ */
+export const parseSafe = (raw: string) =>
+  Effect.try({
+    try: () => JSON.parse(raw) as unknown,
+    catch: () => undefined,
+  }).pipe(Effect.orElseSucceed(() => undefined))
+
 const encoder = new TextEncoder()
 
 /**

package/src/streaming/SSE.ts

@@ -6,7 +6,7 @@ import { Stream } from "effect"
  * - `data`: payload, with multiple `data:` lines joined by `\n`
  * - `id`: optional last-event id
  */
-export interface Event {
+export type Event = {
   readonly event?: string
   readonly data: string
   readonly id?: string

package/src/structured-format/StructuredFormat.ts

@@ -19,7 +19,7 @@ export type StructuredSchema<Output = unknown> = StandardSchemaV1<unknown, Outpu
  * cross-validator schema with metadata providers need (name, description,
  * strict-mode flag).
  */
-export interface StructuredFormat<A> {
+export type StructuredFormat<A> = {
   readonly name: string
   readonly description?: string
   readonly schema: StructuredSchema<A>
@@ -31,7 +31,7 @@ export interface StructuredFormat<A> {
 }
 
 /** A single path-scoped validation problem. Library-agnostic shape. */
-export interface DecodeIssue {
+export type DecodeIssue = {
   readonly path: ReadonlyArray<string | number>
   readonly message: string
 }

package/src/testing/MockMusicGenerator.ts

@@ -0,0 +1,170 @@
+import { Effect, Layer, Ref, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { AudioChunk } from "../domain/Audio.js"
+import type {
+  CommonGenerateMusicRequest,
+  CommonStreamGenerateMusicRequest,
+  MusicResult,
+  MusicSessionInput,
+} from "../domain/Music.js"
+import {
+  MusicGenerator,
+  MusicInteractiveSession,
+  type MusicGeneratorService,
+} from "../music-generator/MusicGenerator.js"
+
+export type MockMusicGeneratorRecorder = {
+  readonly generateCalls: ReadonlyArray<CommonGenerateMusicRequest>
+  readonly streamGenerationCalls: ReadonlyArray<CommonStreamGenerateMusicRequest>
+  readonly streamGenerationFromCalls: ReadonlyArray<CommonStreamGenerateMusicRequest>
+}
+
+export type MockMusicGeneratorScript = {
+  /** One result per `generate` call, consumed in order. */
+  readonly results?: ReadonlyArray<MusicResult>
+  /** One chunk-list per `streamGeneration` call, consumed in order. */
+  readonly streamGenerationChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+  /** One chunk-list per `streamGenerationFrom` call, consumed in order. */
+  readonly streamGenerationFromChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+}
+
+const makeService = (
+  script: MockMusicGeneratorScript,
+  record: {
+    readonly generate: (req: CommonGenerateMusicRequest) => Effect.Effect<void>
+    readonly streamGeneration: (req: CommonStreamGenerateMusicRequest) => Effect.Effect<void>
+    readonly streamGenerationFrom: (req: CommonStreamGenerateMusicRequest) => Effect.Effect<void>
+  },
+) =>
+  Effect.gen(function* () {
+    const gCursor = yield* Ref.make(0)
+    const sgCursor = yield* Ref.make(0)
+    const sgfCursor = yield* Ref.make(0)
+    const service: MusicGeneratorService = {
+      generate: (request) =>
+        Effect.gen(function* () {
+          yield* record.generate(request)
+          const i = yield* Ref.getAndUpdate(gCursor, (n) => n + 1)
+          const scripted = script.results ?? []
+          if (i >= scripted.length) {
+            return yield* Effect.fail(
+              new AiError.InvalidRequest({
+                provider: "mock",
+                raw: `MockMusicGenerator exhausted: ${scripted.length} results scripted, but call ${i + 1} was made`,
+              }),
+            )
+          }
+          return scripted[i]!
+        }),
+      streamGeneration: (request) =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.streamGeneration(request)
+            const i = yield* Ref.getAndUpdate(sgCursor, (n) => n + 1)
+            const scripted = script.streamGenerationChunks ?? []
+            if (i >= scripted.length) {
+              return Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockMusicGenerator exhausted: ${scripted.length} streamGeneration lists scripted, but call ${i + 1} was made`,
+                }),
+              )
+            }
+            return Stream.fromIterable(scripted[i]!)
+          }),
+        ),
+      streamGenerationFrom: <E, R>(
+        input: Stream.Stream<MusicSessionInput, E, R>,
+        request: CommonStreamGenerateMusicRequest,
+      ): Stream.Stream<AudioChunk, AiError.AiError | E, R> =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.streamGenerationFrom(request)
+            const i = yield* Ref.getAndUpdate(sgfCursor, (n) => n + 1)
+            const scripted = script.streamGenerationFromChunks ?? []
+            if (i >= scripted.length) {
+              const exhausted: Stream.Stream<AudioChunk, AiError.AiError | E, R> = Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockMusicGenerator exhausted: ${scripted.length} streamGenerationFrom lists scripted, but call ${i + 1} was made`,
+                }),
+              )
+              return exhausted
+            }
+            // Drain the input fully before emitting scripted audio chunks,
+            // so consumers can assert on what session messages were pushed.
+            return Stream.drain(input).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
+          }),
+        ),
+    }
+    return service
+  })
+
+/**
+ * Layer providing the `MusicGenerator` service AND the
+ * `MusicInteractiveSession` capability marker. Use for the common case
+ * where code under test exercises `streamGenerationFrom`.
+ */
+export const layer = (
+  script: MockMusicGeneratorScript,
+): {
+  readonly layer: Layer.Layer<MusicGenerator | MusicInteractiveSession>
+  readonly recorder: Effect.Effect<MockMusicGeneratorRecorder>
+} => {
+  const gCalls = Ref.makeUnsafe<ReadonlyArray<CommonGenerateMusicRequest>>([])
+  const sgCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamGenerateMusicRequest>>([])
+  const sgfCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamGenerateMusicRequest>>([])
+  const generatorLayer = Layer.effect(
+    MusicGenerator,
+    makeService(script, {
+      generate: (req) => Ref.update(gCalls, (xs) => [...xs, req]),
+      streamGeneration: (req) => Ref.update(sgCalls, (xs) => [...xs, req]),
+      streamGenerationFrom: (req) => Ref.update(sgfCalls, (xs) => [...xs, req]),
+    }),
+  )
+  const live = Layer.merge(generatorLayer, Layer.succeed(MusicInteractiveSession, undefined))
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const generateCalls = yield* Ref.get(gCalls)
+      const streamGenerationCalls = yield* Ref.get(sgCalls)
+      const streamGenerationFromCalls = yield* Ref.get(sgfCalls)
+      return { generateCalls, streamGenerationCalls, streamGenerationFromCalls }
+    }),
+  }
+}
+
+/**
+ * Variant that omits the `MusicInteractiveSession` marker — simulates a
+ * provider without bidirectional support (Lyria 3 sync, ElevenLabs,
+ * Mureka, MiniMax, Stable Audio, Suno). Calls to
+ * `streamGenerationFrom` in code under test should be a compile-time
+ * error against this Layer alone.
+ */
+export const layerWithoutInteractive = (
+  script: MockMusicGeneratorScript,
+): {
+  readonly layer: Layer.Layer<MusicGenerator>
+  readonly recorder: Effect.Effect<MockMusicGeneratorRecorder>
+} => {
+  const gCalls = Ref.makeUnsafe<ReadonlyArray<CommonGenerateMusicRequest>>([])
+  const sgCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamGenerateMusicRequest>>([])
+  const sgfCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamGenerateMusicRequest>>([])
+  const live = Layer.effect(
+    MusicGenerator,
+    makeService(script, {
+      generate: (req) => Ref.update(gCalls, (xs) => [...xs, req]),
+      streamGeneration: (req) => Ref.update(sgCalls, (xs) => [...xs, req]),
+      streamGenerationFrom: (req) => Ref.update(sgfCalls, (xs) => [...xs, req]),
+    }),
+  )
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const generateCalls = yield* Ref.get(gCalls)
+      const streamGenerationCalls = yield* Ref.get(sgCalls)
+      const streamGenerationFromCalls = yield* Ref.get(sgfCalls)
+      return { generateCalls, streamGenerationCalls, streamGenerationFromCalls }
+    }),
+  }
+}

package/src/testing/MockProvider.ts

@@ -4,7 +4,7 @@ import type { Item } from "../domain/Items.js"
 import { LanguageModel, type LanguageModelService } from "../language-model/LanguageModel.js"
 import type { Turn, TurnEvent } from "../domain/Turn.js"
 
-export interface MockOptions {
+export type MockOptions = {
   /**
    * If set, deltas of each scripted turn are spaced by this duration via
    * `Schedule.spaced`. Combine with `TestClock.adjust` for deterministic
@@ -19,7 +19,7 @@ export interface MockOptions {
  * deltas (text → tool_call_start → tool_call_args_delta → ... → turn_complete)
  * so streaming consumers can see realistic delta shapes.
  */
-export interface MockRecorder {
+export type MockRecorder = {
   readonly calls: ReadonlyArray<{
     readonly history: ReadonlyArray<Item>
     readonly turn: Turn

package/src/testing/MockSpeechSynthesizer.ts

@@ -0,0 +1,165 @@
+import { Effect, Layer, Ref, Stream } from "effect"
+import type { AudioBlob, AudioChunk } from "../domain/Audio.js"
+import * as AiError from "../domain/AiError.js"
+import {
+  SpeechSynthesizer,
+  TtsIncrementalText,
+  type CommonStreamSynthesizeRequest,
+  type CommonSynthesizeRequest,
+  type SpeechSynthesizerService,
+} from "../speech-synthesizer/SpeechSynthesizer.js"
+
+export type MockSynthesizerRecorder = {
+  readonly synthesizeCalls: ReadonlyArray<CommonSynthesizeRequest>
+  readonly streamSynthesisCalls: ReadonlyArray<CommonSynthesizeRequest>
+  readonly streamSynthesisFromCalls: ReadonlyArray<CommonStreamSynthesizeRequest>
+}
+
+export type MockSynthesizerScript = {
+  /** One blob per `synthesize` call, consumed in order. */
+  readonly blobs?: ReadonlyArray<AudioBlob>
+  /** One chunk-list per `streamSynthesis` call, consumed in order. */
+  readonly streamSynthesisChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+  /** One chunk-list per `streamSynthesisFrom` call, consumed in order. */
+  readonly streamSynthesisFromChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+}
+
+const makeService = (
+  script: MockSynthesizerScript,
+  record: {
+    readonly synthesize: (req: CommonSynthesizeRequest) => Effect.Effect<void>
+    readonly streamSynthesis: (req: CommonSynthesizeRequest) => Effect.Effect<void>
+    readonly streamSynthesisFrom: (req: CommonStreamSynthesizeRequest) => Effect.Effect<void>
+  },
+) =>
+  Effect.gen(function* () {
+    const bCursor = yield* Ref.make(0)
+    const ssCursor = yield* Ref.make(0)
+    const ssfCursor = yield* Ref.make(0)
+    const service: SpeechSynthesizerService = {
+      synthesize: (request) =>
+        Effect.gen(function* () {
+          yield* record.synthesize(request)
+          const i = yield* Ref.getAndUpdate(bCursor, (n) => n + 1)
+          const scripted = script.blobs ?? []
+          if (i >= scripted.length) {
+            return yield* Effect.fail(
+              new AiError.InvalidRequest({
+                provider: "mock",
+                raw: `MockSpeechSynthesizer exhausted: ${scripted.length} blobs scripted, but call ${i + 1} was made`,
+              }),
+            )
+          }
+          return scripted[i]!
+        }),
+      streamSynthesis: (request) =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.streamSynthesis(request)
+            const i = yield* Ref.getAndUpdate(ssCursor, (n) => n + 1)
+            const scripted = script.streamSynthesisChunks ?? []
+            if (i >= scripted.length) {
+              return Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockSpeechSynthesizer exhausted: ${scripted.length} streamSynthesis lists scripted, but call ${i + 1} was made`,
+                }),
+              )
+            }
+            return Stream.fromIterable(scripted[i]!)
+          }),
+        ),
+      streamSynthesisFrom: <E, R>(
+        textIn: Stream.Stream<string, E, R>,
+        request: CommonStreamSynthesizeRequest,
+      ): Stream.Stream<AudioChunk, AiError.AiError | E, R> =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.streamSynthesisFrom(request)
+            const i = yield* Ref.getAndUpdate(ssfCursor, (n) => n + 1)
+            const scripted = script.streamSynthesisFromChunks ?? []
+            if (i >= scripted.length) {
+              const exhausted: Stream.Stream<AudioChunk, AiError.AiError | E, R> = Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockSpeechSynthesizer exhausted: ${scripted.length} streamSynthesisFrom lists scripted, but call ${i + 1} was made`,
+                }),
+              )
+              return exhausted
+            }
+            // Drain the input text fully before emitting scripted audio chunks,
+            // so consumers can assert on what text was pushed.
+            return Stream.drain(textIn).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
+          }),
+        ),
+    }
+    return service
+  })
+
+/**
+ * Layer providing the `SpeechSynthesizer` service AND the
+ * `TtsIncrementalText` capability marker. Use for the common case
+ * where code under test exercises `streamSynthesisFrom`.
+ */
+export const layer = (
+  script: MockSynthesizerScript,
+): {
+  readonly layer: Layer.Layer<SpeechSynthesizer | TtsIncrementalText>
+  readonly recorder: Effect.Effect<MockSynthesizerRecorder>
+} => {
+  const bCalls = Ref.makeUnsafe<ReadonlyArray<CommonSynthesizeRequest>>([])
+  const ssCalls = Ref.makeUnsafe<ReadonlyArray<CommonSynthesizeRequest>>([])
+  const ssfCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamSynthesizeRequest>>([])
+  const synthesizerLayer = Layer.effect(
+    SpeechSynthesizer,
+    makeService(script, {
+      synthesize: (req) => Ref.update(bCalls, (xs) => [...xs, req]),
+      streamSynthesis: (req) => Ref.update(ssCalls, (xs) => [...xs, req]),
+      streamSynthesisFrom: (req) => Ref.update(ssfCalls, (xs) => [...xs, req]),
+    }),
+  )
+  const live = Layer.merge(synthesizerLayer, Layer.succeed(TtsIncrementalText, undefined))
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const synthesizeCalls = yield* Ref.get(bCalls)
+      const streamSynthesisCalls = yield* Ref.get(ssCalls)
+      const streamSynthesisFromCalls = yield* Ref.get(ssfCalls)
+      return { synthesizeCalls, streamSynthesisCalls, streamSynthesisFromCalls }
+    }),
+  }
+}
+
+/**
+ * Variant that omits the `TtsIncrementalText` marker — simulates a
+ * provider without incremental-text-in support (e.g. OpenAI, AWS
+ * Polly non-Generative). Calls to `streamSynthesisFrom` in code under
+ * test should be a compile-time error.
+ */
+export const layerWithoutIncremental = (
+  script: MockSynthesizerScript,
+): {
+  readonly layer: Layer.Layer<SpeechSynthesizer>
+  readonly recorder: Effect.Effect<MockSynthesizerRecorder>
+} => {
+  const bCalls = Ref.makeUnsafe<ReadonlyArray<CommonSynthesizeRequest>>([])
+  const ssCalls = Ref.makeUnsafe<ReadonlyArray<CommonSynthesizeRequest>>([])
+  const ssfCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamSynthesizeRequest>>([])
+  const live = Layer.effect(
+    SpeechSynthesizer,
+    makeService(script, {
+      synthesize: (req) => Ref.update(bCalls, (xs) => [...xs, req]),
+      streamSynthesis: (req) => Ref.update(ssCalls, (xs) => [...xs, req]),
+      streamSynthesisFrom: (req) => Ref.update(ssfCalls, (xs) => [...xs, req]),
+    }),
+  )
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const synthesizeCalls = yield* Ref.get(bCalls)
+      const streamSynthesisCalls = yield* Ref.get(ssCalls)
+      const streamSynthesisFromCalls = yield* Ref.get(ssfCalls)
+      return { synthesizeCalls, streamSynthesisCalls, streamSynthesisFromCalls }
+    }),
+  }
+}

package/src/testing/MockTranscriber.ts

@@ -0,0 +1,139 @@
+import { Effect, Layer, Ref, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { TranscriptEvent, TranscriptResult } from "../domain/Transcript.js"
+import {
+  SttStreaming,
+  Transcriber,
+  type CommonStreamTranscribeRequest,
+  type CommonTranscribeRequest,
+  type TranscriberService,
+} from "../transcriber/Transcriber.js"
+
+/**
+ * Recorder of every call made to the mock.
+ */
+export type MockTranscriberRecorder = {
+  readonly transcribeCalls: ReadonlyArray<CommonTranscribeRequest>
+  readonly streamCalls: ReadonlyArray<CommonStreamTranscribeRequest>
+}
+
+export type MockTranscriberScript = {
+  /** One result per `transcribe` call, consumed in order. */
+  readonly transcripts?: ReadonlyArray<TranscriptResult>
+  /** One event-list per `streamTranscriptionFrom` call, consumed in order. */
+  readonly streams?: ReadonlyArray<ReadonlyArray<TranscriptEvent>>
+}
+
+const makeService = (
+  script: MockTranscriberScript,
+  record: {
+    readonly transcribe: (req: CommonTranscribeRequest) => Effect.Effect<void>
+    readonly stream: (req: CommonStreamTranscribeRequest) => Effect.Effect<void>
+  },
+) =>
+  Effect.gen(function* () {
+    const tCursor = yield* Ref.make(0)
+    const sCursor = yield* Ref.make(0)
+    const service: TranscriberService = {
+      transcribe: (request) =>
+        Effect.gen(function* () {
+          yield* record.transcribe(request)
+          const i = yield* Ref.getAndUpdate(tCursor, (n) => n + 1)
+          const scripted = script.transcripts ?? []
+          if (i >= scripted.length) {
+            return yield* Effect.fail(
+              new AiError.InvalidRequest({
+                provider: "mock",
+                raw: `MockTranscriber exhausted: ${scripted.length} transcripts scripted, but call ${i + 1} was made`,
+              }),
+            )
+          }
+          return scripted[i]!
+        }),
+      streamTranscriptionFrom: <E, R>(
+        audioIn: Stream.Stream<Uint8Array, E, R>,
+        request: CommonStreamTranscribeRequest,
+      ): Stream.Stream<TranscriptEvent, AiError.AiError | E, R> =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.stream(request)
+            const i = yield* Ref.getAndUpdate(sCursor, (n) => n + 1)
+            const scripted = script.streams ?? []
+            if (i >= scripted.length) {
+              const exhausted: Stream.Stream<TranscriptEvent, AiError.AiError | E, R> = Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockTranscriber exhausted: ${scripted.length} streams scripted, but call ${i + 1} was made`,
+                }),
+              )
+              return exhausted
+            }
+            // Drain the input audio fully before emitting the scripted events,
+            // so consumers can assert on what bytes were pushed.
+            return Stream.drain(audioIn).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
+          }),
+        ),
+    }
+    return service
+  })
+
+/**
+ * Returns a Layer that provides both the `Transcriber` service and the
+ * `SttStreaming` capability marker. Use when the code under test calls
+ * `streamTranscriptionFrom`.
+ */
+export const layer = (
+  script: MockTranscriberScript,
+): {
+  readonly layer: Layer.Layer<Transcriber | SttStreaming>
+  readonly recorder: Effect.Effect<MockTranscriberRecorder>
+} => {
+  const tCalls = Ref.makeUnsafe<ReadonlyArray<CommonTranscribeRequest>>([])
+  const sCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamTranscribeRequest>>([])
+  const transcriberLayer = Layer.effect(
+    Transcriber,
+    makeService(script, {
+      transcribe: (req) => Ref.update(tCalls, (xs) => [...xs, req]),
+      stream: (req) => Ref.update(sCalls, (xs) => [...xs, req]),
+    }),
+  )
+  const live = Layer.merge(transcriberLayer, Layer.succeed(SttStreaming, undefined))
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const transcribeCalls = yield* Ref.get(tCalls)
+      const streamCalls = yield* Ref.get(sCalls)
+      return { transcribeCalls, streamCalls }
+    }),
+  }
+}
+
+/**
+ * Variant that omits the `SttStreaming` marker — use to test that
+ * consumers calling `streamTranscriptionFrom` fail to compile against
+ * a non-streaming provider.
+ */
+export const layerSyncOnly = (
+  script: MockTranscriberScript,
+): {
+  readonly layer: Layer.Layer<Transcriber>
+  readonly recorder: Effect.Effect<MockTranscriberRecorder>
+} => {
+  const tCalls = Ref.makeUnsafe<ReadonlyArray<CommonTranscribeRequest>>([])
+  const sCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamTranscribeRequest>>([])
+  const live = Layer.effect(
+    Transcriber,
+    makeService(script, {
+      transcribe: (req) => Ref.update(tCalls, (xs) => [...xs, req]),
+      stream: (req) => Ref.update(sCalls, (xs) => [...xs, req]),
+    }),
+  )
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const transcribeCalls = yield* Ref.get(tCalls)
+      const streamCalls = yield* Ref.get(sCalls)
+      return { transcribeCalls, streamCalls }
+    }),
+  }
+}