@effect-uai/core 0.3.0 → 0.5.0

package/src/music-generator/MusicGenerator.ts

@@ -0,0 +1,123 @@
+import { Context, Effect, Function, 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"
+
+export type {
+  CommonGenerateMusicRequest,
+  CommonStreamGenerateMusicRequest,
+  MusicResult,
+  MusicSessionInput,
+  WeightedPrompt,
+} from "../domain/Music.js"
+
+export type MusicGeneratorService = {
+  /**
+   * One-shot. Prompt in, full audio bytes out. Universally supported.
+   * Async/poll-based providers (Suno, Mureka) hide their poll loop
+   * inside the adapter — caller still sees a single `Effect`.
+   */
+  readonly generate: (
+    request: CommonGenerateMusicRequest,
+  ) => Effect.Effect<MusicResult, AiError.AiError>
+  /**
+   * Prompt in, audio chunks streamed out. Providers without a native
+   * chunked-output endpoint (Lyria 3 sync, Mureka, MiniMax, Stable
+   * Audio) emulate this by calling `generate` and emitting a single
+   * `AudioChunk` — first-class, no `Unsupported`.
+   */
+  readonly streamGeneration: (
+    request: CommonStreamGenerateMusicRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  /**
+   * Bidirectional session: a `Stream` of prompt-or-config updates flows
+   * in, a `Stream` of audio chunks flows out. The session WS / RPC is
+   * acquired on first pull and released when the output stream is
+   * finalized via `Stream.scoped`.
+   *
+   * Gated by the `MusicInteractiveSession` capability marker on the
+   * top-level helper — providers without bidirectional support don't
+   * ship the marker, so calls fail at `Effect.provide` with a type
+   * error.
+   */
+  readonly streamGenerationFrom: <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+    request: CommonStreamGenerateMusicRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+}
+
+export class MusicGenerator extends Context.Service<MusicGenerator, MusicGeneratorService>()(
+  "@betalyra/effect-uai/MusicGenerator",
+) {}
+
+/**
+ * Capability marker — provided by provider layers whose
+ * `streamGenerationFrom` is wired up at the wire level. Currently only
+ * Lyria RealTime (via the BidiGenerateMusic WebSocket) ships it.
+ * Calling `streamGenerationFrom` while only a non-interactive Layer is
+ * in scope fails at `Effect.provide` with a type error.
+ *
+ * Phantom — the value is `void`; providers register with
+ * `Layer.succeed(MusicInteractiveSession, undefined)`.
+ */
+export class MusicInteractiveSession extends Context.Service<MusicInteractiveSession, void>()(
+  "@betalyra/effect-uai/capability/MusicInteractiveSession",
+) {}
+
+/** One-shot generation. */
+export const generate = (
+  request: CommonGenerateMusicRequest,
+): Effect.Effect<MusicResult, AiError.AiError, MusicGenerator> =>
+  Effect.flatMap(MusicGenerator.asEffect(), (s) => s.generate(request))
+
+/** Prompt in, audio chunks out. */
+export const streamGeneration = (
+  request: CommonStreamGenerateMusicRequest,
+): Stream.Stream<AudioChunk, AiError.AiError, MusicGenerator> =>
+  Stream.unwrap(Effect.map(MusicGenerator.asEffect(), (s) => s.streamGeneration(request)))
+
+/**
+ * Bidirectional generation. Dual-arity: pipeable (data-last) and
+ * direct (data-first). Requires `MusicInteractiveSession` in R —
+ * providers without bidirectional support are a type error at provide
+ * time.
+ *
+ * @example
+ * ```ts
+ * const audio = Stream.fromIterable([
+ *   Music.promptsInput([{ text: "minimal techno", weight: 1.0 }]),
+ *   Music.configInput({ bpm: 124 }),
+ * ]).pipe(
+ *   MusicGenerator.streamGenerationFrom({ model: "lyria-realtime-001", prompts: "" }),
+ * )
+ * ```
+ */
+export const streamGenerationFrom: {
+  (
+    request: CommonStreamGenerateMusicRequest,
+  ): <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R | MusicGenerator | MusicInteractiveSession>
+  <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+    request: CommonStreamGenerateMusicRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError | E, R | MusicGenerator | MusicInteractiveSession>
+} = Function.dual(
+  2,
+  <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+    request: CommonStreamGenerateMusicRequest,
+  ) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const s = yield* MusicGenerator.asEffect()
+        yield* MusicInteractiveSession.asEffect()
+        return s.streamGenerationFrom(input, request)
+      }),
+    ),
+)

package/src/observability/Metrics.ts

@@ -52,7 +52,7 @@ export type RatePoint<A> = {
  * The weight is the unit you care about - bytes, tokens, error count, etc.
  * For tokens-per-second on `TurnEvent`, pass:
  *
- *   `(d) => d.type === "text_delta" ? countTokens(d.text) : 0`
+ *   `(d) => d._tag === "TextDelta" ? countTokens(d.text) : 0`
  *
  * Use any tokenizer you like; the library does not ship one.
  */

package/src/speech-synthesizer/SpeechSynthesizer.test.ts

@@ -0,0 +1,141 @@
+import { Effect, Stream } from "effect"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import type * as AiError from "../domain/AiError.js"
+import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
+import * as MockSpeechSynthesizer from "../testing/MockSpeechSynthesizer.js"
+import * as SpeechSynthesizer from "./SpeechSynthesizer.js"
+
+const pcmFormat: AudioFormat = {
+  container: "raw",
+  encoding: "pcm_s16le",
+  sampleRate: 24000,
+}
+
+const blob: AudioBlob = {
+  format: pcmFormat,
+  bytes: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
+  durationSeconds: 0.5,
+}
+
+const chunk = (n: number): AudioChunk => ({ bytes: new Uint8Array([n]) })
+
+describe("SpeechSynthesizer.synthesize", () => {
+  it("returns the scripted AudioBlob", async () => {
+    const mock = MockSpeechSynthesizer.layer({ blobs: [blob] })
+    const program = SpeechSynthesizer.synthesize({
+      text: "hi",
+      model: "mock-tts",
+      voiceId: "stock-voice",
+    })
+    const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(result.bytes).toEqual(blob.bytes)
+    expect(result.durationSeconds).toBe(0.5)
+  })
+})
+
+describe("SpeechSynthesizer.streamSynthesis", () => {
+  it("emits scripted chunks for full-text-in streaming", async () => {
+    const mock = MockSpeechSynthesizer.layer({
+      streamSynthesisChunks: [[chunk(1), chunk(2), chunk(3)]],
+    })
+    const program = Stream.runCollect(
+      SpeechSynthesizer.streamSynthesis({
+        text: "hi",
+        model: "mock-tts",
+        voiceId: "stock-voice",
+      }),
+    )
+    const out = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(out.map((c) => Array.from(c.bytes))).toEqual([[1], [2], [3]])
+  })
+})
+
+describe("SpeechSynthesizer capability marker (compile-time)", () => {
+  const ssfReq: SpeechSynthesizer.CommonStreamSynthesizeRequest = {
+    model: "mock-tts",
+    voiceId: "v",
+  }
+
+  it("requires `TtsIncrementalText` on the R channel of streamSynthesisFrom", () => {
+    const tokens: Stream.Stream<string> = Stream.fromIterable(["a"])
+    const audio = tokens.pipe(SpeechSynthesizer.streamSynthesisFrom(ssfReq))
+    expectTypeOf(audio).toEqualTypeOf<
+      Stream.Stream<
+        AudioChunk,
+        AiError.AiError,
+        SpeechSynthesizer.SpeechSynthesizer | SpeechSynthesizer.TtsIncrementalText
+      >
+    >()
+  })
+
+  it("does NOT require `TtsIncrementalText` for sync `synthesize`", () => {
+    const eff = SpeechSynthesizer.synthesize({ text: "hi", model: "m", voiceId: "v" })
+    expectTypeOf(eff).toEqualTypeOf<
+      Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer.SpeechSynthesizer>
+    >()
+  })
+
+  it("does NOT require `TtsIncrementalText` for full-text `streamSynthesis`", () => {
+    const audio = SpeechSynthesizer.streamSynthesis({ text: "hi", model: "m", voiceId: "v" })
+    expectTypeOf(audio).toEqualTypeOf<
+      Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer.SpeechSynthesizer>
+    >()
+  })
+
+  it("a layer without the marker leaves `TtsIncrementalText` unsatisfied in R", () => {
+    const noMarker = MockSpeechSynthesizer.layerWithoutIncremental({})
+    const tokens: Stream.Stream<string> = Stream.fromIterable(["a"])
+    const audio = tokens.pipe(SpeechSynthesizer.streamSynthesisFrom(ssfReq))
+    const program = Stream.runDrain(audio).pipe(Effect.provide(noMarker.layer))
+    // `SpeechSynthesizer` is provided by the layer; `TtsIncrementalText` is not,
+    // so it remains in R — calling `Effect.runPromise(program)` would be a type
+    // error because runPromise requires `R = never`.
+    expectTypeOf(program).toEqualTypeOf<
+      Effect.Effect<void, AiError.AiError, SpeechSynthesizer.TtsIncrementalText>
+    >()
+  })
+
+  it("a full layer (with marker) clears R to never", () => {
+    const fullMock = MockSpeechSynthesizer.layer({
+      streamSynthesisFromChunks: [[]],
+    })
+    const tokens: Stream.Stream<string> = Stream.fromIterable(["a"])
+    const audio = tokens.pipe(SpeechSynthesizer.streamSynthesisFrom(ssfReq))
+    const program = Stream.runDrain(audio).pipe(Effect.provide(fullMock.layer))
+    expectTypeOf(program).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()
+  })
+})
+
+describe("SpeechSynthesizer.streamSynthesisFrom", () => {
+  const ssfReq: SpeechSynthesizer.CommonStreamSynthesizeRequest = {
+    model: "mock-tts",
+    voiceId: "stock-voice",
+  }
+
+  it("pipes an LLM-style text stream into audio chunks", async () => {
+    const mock = MockSpeechSynthesizer.layer({
+      streamSynthesisFromChunks: [[chunk(10), chunk(20)]],
+    })
+    const tokens = Stream.fromIterable(["Hello, ", "world."])
+    const audio = tokens.pipe(SpeechSynthesizer.streamSynthesisFrom(ssfReq))
+    const out = await Effect.runPromise(Stream.runCollect(audio).pipe(Effect.provide(mock.layer)))
+    expect(out.map((c) => Array.from(c.bytes))).toEqual([[10], [20]])
+  })
+
+  it("records the request on the streamSynthesisFrom call channel", async () => {
+    const mock = MockSpeechSynthesizer.layer({
+      streamSynthesisFromChunks: [[chunk(42)]],
+    })
+    const program = Effect.gen(function* () {
+      yield* Stream.runDrain(
+        Stream.fromIterable(["x"]).pipe(SpeechSynthesizer.streamSynthesisFrom(ssfReq)),
+      )
+      return yield* mock.recorder
+    })
+    const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(rec.streamSynthesisFromCalls.length).toBe(1)
+    expect(rec.streamSynthesisFromCalls[0]!.voiceId).toBe("stock-voice")
+    expect(rec.synthesizeCalls.length).toBe(0)
+    expect(rec.streamSynthesisCalls.length).toBe(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

@@ -61,23 +61,26 @@ export const fromBytes = <E, R>(
  * decode errors both surface as a `JsonParseError` so callers can `catchTag`
  * uniformly.
  */
-export const parse =
-  <A, I>(schema: Schema.Codec<A, I>) =>
-  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<A, JsonParseError | E, R> =>
+export const parse = <A, I>(schema: Schema.Codec<A, I>) => {
+  const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
+  return <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<A, JsonParseError | E, R> =>
     self.pipe(
       Stream.mapEffect((line) =>
-        Effect.try({
-          try: () => JSON.parse(line) as unknown,
-          catch: (cause) => new JsonParseError({ line, cause }),
-        }).pipe(
-          Effect.flatMap((value) =>
-            Schema.decodeUnknownEffect(schema)(value).pipe(
-              Effect.mapError((cause) => new JsonParseError({ line, cause })),
-            ),
-          ),
-        ),
+        decode(line).pipe(Effect.mapError((cause) => new JsonParseError({ line, cause }))),
       ),
     )
+}
+
+const decodeUnknownFromJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+
+/**
+ * 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.Effect<unknown> =>
+  decodeUnknownFromJson(raw).pipe(Effect.orElseSucceed(() => undefined))
 
 const encoder = new TextEncoder()
 

package/src/structured-format/StructuredFormat.test.ts

@@ -0,0 +1,105 @@
+import { Effect, Exit, Filter, Result, Schema, Stream } from "effect"
+import { describe, expect, it } from "vitest"
+import {
+  decodeJsonLines,
+  decodeJsonLinesRecoverable,
+  fromEffectSchema,
+  JsonParseError,
+  StructuredDecodeError,
+} from "./StructuredFormat.js"
+
+const Item = Schema.Struct({ id: Schema.Number, name: Schema.String })
+type Item = typeof Item.Type
+const itemFormat = fromEffectSchema(Item, { name: "Item" })
+
+const linesOf = (...xs: ReadonlyArray<string>): Stream.Stream<string> => Stream.fromIterable(xs)
+
+const collect = <A, E>(s: Stream.Stream<A, E>) =>
+  Effect.runPromise(Stream.runCollect(s).pipe(Effect.map((c) => Array.from(c))))
+
+describe("decodeJsonLinesRecoverable", () => {
+  it("yields a Success for each well-formed line", async () => {
+    const out = await collect(
+      linesOf('{"id":1,"name":"a"}', '{"id":2,"name":"b"}').pipe(
+        decodeJsonLinesRecoverable(itemFormat),
+      ),
+    )
+
+    expect(out).toHaveLength(2)
+    expect(Result.isSuccess(out[0]!)).toBe(true)
+    expect(Result.isSuccess(out[1]!)).toBe(true)
+    if (Result.isSuccess(out[0]!) && Result.isSuccess(out[1]!)) {
+      expect(out[0]!.success).toEqual<Item>({ id: 1, name: "a" })
+      expect(out[1]!.success).toEqual<Item>({ id: 2, name: "b" })
+    }
+  })
+
+  it("yields a Failure for a malformed JSON line WITHOUT aborting the stream", async () => {
+    const out = await collect(
+      linesOf('{"id":1,"name":"a"}', "not json at all", '{"id":3,"name":"c"}').pipe(
+        decodeJsonLinesRecoverable(itemFormat),
+      ),
+    )
+
+    expect(out).toHaveLength(3)
+    expect(Result.isSuccess(out[0]!)).toBe(true)
+    expect(Result.isFailure(out[1]!)).toBe(true)
+    expect(Result.isSuccess(out[2]!)).toBe(true)
+    if (Result.isFailure(out[1]!)) {
+      expect(out[1]!.failure).toBeInstanceOf(JsonParseError)
+    }
+  })
+
+  it("yields a Failure for a schema-invalid line without aborting", async () => {
+    const out = await collect(
+      linesOf(
+        '{"id":1,"name":"a"}',
+        '{"id":"not-a-number","name":"b"}', // schema fail
+        '{"id":3,"name":"c"}',
+      ).pipe(decodeJsonLinesRecoverable(itemFormat)),
+    )
+
+    expect(out).toHaveLength(3)
+    expect(Result.isSuccess(out[0]!)).toBe(true)
+    expect(Result.isFailure(out[1]!)).toBe(true)
+    expect(Result.isSuccess(out[2]!)).toBe(true)
+    if (Result.isFailure(out[1]!)) {
+      expect(out[1]!.failure).toBeInstanceOf(StructuredDecodeError)
+    }
+  })
+
+  it("propagates upstream errors normally (only DECODE failures are lifted into Result)", async () => {
+    const boom = new Error("upstream broke")
+    const stream = Stream.concat(linesOf('{"id":1,"name":"a"}'), Stream.fail(boom)).pipe(
+      decodeJsonLinesRecoverable(itemFormat),
+    )
+
+    const exit = await Effect.runPromise(Effect.exit(Stream.runCollect(stream)))
+    expect(Exit.isFailure(exit)).toBe(true)
+  })
+
+  it("composes with filter-success / log-and-continue", async () => {
+    const out = await collect(
+      linesOf('{"id":1,"name":"a"}', "garbage", '{"id":2,"name":"b"}').pipe(
+        decodeJsonLinesRecoverable(itemFormat),
+        Stream.filterMap(Filter.fromPredicateOption(Result.getSuccess)),
+      ),
+    )
+
+    expect(out).toEqual<Array<Item>>([
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+    ])
+  })
+})
+
+describe("decodeJsonLines (fail-fast, sanity)", () => {
+  it("aborts the stream on the first bad line", async () => {
+    const stream = linesOf('{"id":1,"name":"a"}', "garbage", '{"id":3,"name":"c"}').pipe(
+      decodeJsonLines(itemFormat),
+    )
+
+    const exit = await Effect.runPromise(Effect.exit(Stream.runCollect(stream)))
+    expect(Exit.isFailure(exit)).toBe(true)
+  })
+})

package/src/structured-format/StructuredFormat.ts

@@ -1,5 +1,5 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Data, Effect, Match, Schema, Stream, pipe } from "effect"
+import { Data, Effect, Match, Result, Schema, Stream, pipe } from "effect"
 
 // ---------------------------------------------------------------------------
 // Types
@@ -158,3 +158,16 @@ export const decodeJsonLines =
     self: Stream.Stream<string, E, R>,
   ): Stream.Stream<A, E | JsonParseError | StructuredDecodeError, R> =>
     self.pipe(Stream.mapEffect(parseJson(format)))
+
+/**
+ * Like {@link decodeJsonLines}, but each line yields a `Result` instead of
+ * failing the stream. Use when one bad line shouldn't abort the rest —
+ * log-and-continue, or partial-recovery with a corrective re-prompt.
+ * Upstream errors (the input stream's own `E`) still propagate normally.
+ */
+export const decodeJsonLinesRecoverable =
+  <A>(format: StructuredFormat<A>) =>
+  <E, R>(
+    self: Stream.Stream<string, E, R>,
+  ): Stream.Stream<Result.Result<A, JsonParseError | StructuredDecodeError>, E, R> =>
+    self.pipe(Stream.mapEffect((line) => Effect.result(parseJson(format)(line))))