@effect-uai/core 0.4.0 → 0.5.1

package/src/loop/Loop.ts

@@ -18,14 +18,17 @@
  * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.
  */
 import {
+  Array as Arr,
   Cause,
   Channel,
   Data,
   Effect,
   Exit,
   Function,
+  Match,
   Option,
   Ref,
+  Result,
   Scope,
   Stream,
   SubscriptionRef,
@@ -40,12 +43,22 @@ import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 /**
  * The tagged union a body emits per pull. `Value` carries a payload that
  * flows downstream. `Next` ends the current iteration and continues with a
- * new state. `Stop` ends the loop entirely.
+ * new state. `Stop` ends the loop entirely with no carried state.
+ * `StopWith` also ends the loop but carries a final state that `loopFrom`
+ * will thread to the next input and `loopWithState` will write to its
+ * `SubscriptionRef` before the loop ends. Plain `loop` has no next
+ * iteration to apply it to and treats `StopWith` like `Stop`.
+ *
+ * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers
+ * don't constrain `S` from a body's stream type — every body has a `Stop`
+ * variant in its union, and forcing `S` to flow through it would break
+ * inference whenever the body never uses `next` / `stopWith`.
  */
 export type Event<A, S> = Data.TaggedEnum<{
   Value: { readonly value: A }
   Next: { readonly state: S }
   Stop: {}
+  StopWith: { readonly state: S }
 }>
 
 interface EventDef extends Data.TaggedEnum.WithGenerics<2> {
@@ -60,9 +73,21 @@ export const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })
 /** End the current iteration and continue with a new state. */
 export const next = <S>(state: S): Event<never, S> => Event.Next({ state })
 
-/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */
+/**
+ * The terminal `Stop` event with no carried state. Use `stop` (the Stream)
+ * to end a loop body without communicating a final state.
+ */
 export const stopEvent: Event<never, never> = Event.Stop()
 
+/**
+ * Terminal event that ends the loop AND carries a final state. For
+ * `loopFrom` this is the natural "this input is done, here's the state to
+ * carry forward to the next input" signal — symmetric with `next(s)` but
+ * ending the inner loop instead of continuing it. For `loopWithState` the
+ * carried state is written to the `SubscriptionRef` before the loop ends.
+ */
+export const stopWith = <S>(state: S): Event<never, S> => Event.StopWith({ state })
+
 /**
  * A single-element stream that ends the loop. Return this from a body when
  * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but
@@ -74,22 +99,47 @@ export const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent
  * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
  * iteration with `next(state)`. Common shape for "stream this turn's
  * deltas, then continue with updated history."
+ *
+ * Dual: data-first `nextAfter(stream, state)` and data-last
+ * `stream.pipe(nextAfter(state))` both work.
  */
-export const nextAfter = <S, A, E, R>(
-  stream: Stream.Stream<A, E, R>,
-  state: S,
-): Stream.Stream<Event<A, S>, E, R> =>
-  Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]))
+export const nextAfter: {
+  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>
+} = Function.dual(
+  2,
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>
+    Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)])),
+)
 
 /**
  * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
  * loop. Common shape for "stream this turn's deltas, then we're done."
+ *
+ * Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.
  */
 export const stopAfter = <A, E, R>(
   stream: Stream.Stream<A, E, R>,
 ): Stream.Stream<Event<A, never>, E, R> =>
   Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))
 
+/**
+ * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with
+ * `stopWith(state)`. The natural "emit final outputs, advance state, end
+ * this input's inner loop" shape for `loopFrom`.
+ *
+ * Dual: data-first `stopWithAfter(stream, state)` and data-last
+ * `stream.pipe(stopWithAfter(state))` both work.
+ */
+export const stopWithAfter: {
+  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>
+} = Function.dual(
+  2,
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>
+    Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(state)])),
+)
+
 /**
  * General `nextAfter` variant: drain `stream` to the consumer, fold elements
  * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
@@ -97,26 +147,44 @@ export const stopAfter = <A, E, R>(
  * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,
  * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool
  * results and build next state without exposing a Ref to recipes.
+ *
+ * Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and
+ * data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.
  */
-export const nextAfterFold = <A, B, S, E, R>(
-  stream: Stream.Stream<A, E, R>,
-  initial: B,
-  reduce: (acc: B, a: A) => B,
-  build: (b: B) => S,
-): Stream.Stream<Event<A, S>, E, R> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const ref = yield* Ref.make(initial)
-      const tapped = stream.pipe(
-        Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),
-        Stream.map(value),
-      )
-      const continuation = Stream.fromEffect(
-        Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),
-      )
-      return tapped.pipe(Stream.concat(continuation))
-    }),
-  )
+export const nextAfterFold: {
+  <A, B, S>(
+    initial: B,
+    reduce: (acc: B, a: A) => B,
+    build: (b: B) => S,
+  ): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
+  <A, B, S, E, R>(
+    stream: Stream.Stream<A, E, R>,
+    initial: B,
+    reduce: (acc: B, a: A) => B,
+    build: (b: B) => S,
+  ): Stream.Stream<Event<A, S>, E, R>
+} = Function.dual(
+  4,
+  <A, B, S, E, R>(
+    stream: Stream.Stream<A, E, R>,
+    initial: B,
+    reduce: (acc: B, a: A) => B,
+    build: (b: B) => S,
+  ): Stream.Stream<Event<A, S>, E, R> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const ref = yield* Ref.make(initial)
+        const tapped = stream.pipe(
+          Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),
+          Stream.map(value),
+        )
+        const continuation = Stream.fromEffect(
+          Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),
+        )
+        return tapped.pipe(Stream.concat(continuation))
+      }),
+    ),
+)
 
 // ---------------------------------------------------------------------------
 // onTurnComplete - turn-aware stream operator for loop bodies
@@ -125,7 +193,7 @@ export const nextAfterFold = <A, B, S, E, R>(
 /**
  * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
  * Each delta passes through as `value(delta)` (including the terminal
- * `turn_complete`, so the consumer sees turn boundaries naturally). Once
+ * `TurnComplete`, so the consumer sees turn boundaries naturally). Once
  * the terminal arrives, `then(turn)` runs and its returned stream of loop
  * events (typically tool outputs followed by `next(state)` or `stop`) is
  * concatenated.
@@ -133,16 +201,28 @@ export const nextAfterFold = <A, B, S, E, R>(
  * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
  * the raw delta stream cover anything an `emit`-style callback would do.
  *
- * If the upstream ends without a `turn_complete`, the resulting stream
+ * If the upstream ends without a `TurnComplete`, the resulting stream
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
+ *
+ * Dual: data-first `onTurnComplete(deltas, then)` and data-last
+ * `deltas.pipe(onTurnComplete(then))` both work.
  */
-export const onTurnComplete =
+export const onTurnComplete: {
   <S, A, E2 = never, R2 = never>(
     then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
-  ) =>
-  <E, R>(
+  ): <E, R>(
+    deltas: Stream.Stream<TurnEvent, E, R>,
+  ) => Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
+  <S, A, E, R, E2 = never, R2 = never>(
     deltas: Stream.Stream<TurnEvent, E, R>,
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
+  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
+} = Function.dual(
+  2,
+  <S, A, E, R, E2, R2>(
+    deltas: Stream.Stream<TurnEvent, E, R>,
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
   ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
     Stream.unwrap(
       Effect.gen(function* () {
@@ -158,14 +238,15 @@ export const onTurnComplete =
         const continuation = Stream.unwrap(
           Effect.gen(function* () {
             const opt = yield* Ref.get(turnRef)
-            if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}))
+            if (Option.isNone(opt)) return yield* new IncompleteTurn({})
             return yield* then(opt.value)
           }),
         )
 
         return Stream.concat(events, continuation)
       }),
-    )
+    ),
+)
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -192,17 +273,18 @@ const closeBody = <S, A, E, R>(
  */
 const partitionChunk = <A, S>(
   chunk: ReadonlyArray<Event<A, S>>,
-): { readonly values: Array<A>; readonly decision: Event<A, S> | undefined } => {
-  const values: Array<A> = []
-  for (let i = 0; i < chunk.length; i++) {
-    const event = chunk[i]!
-    if (event._tag === "Value") {
-      values.push(event.value)
-    } else {
-      return { values, decision: event }
-    }
+): {
+  readonly values: ReadonlyArray<A>
+  readonly decision: Option.Option<Event<A, S>>
+} => {
+  const [valueEvents, rest] = Arr.span(
+    chunk,
+    (e): e is Event<A, S> & { _tag: "Value" } => e._tag === "Value",
+  )
+  return {
+    values: valueEvents.map((e) => e.value),
+    decision: Arr.head(rest),
   }
-  return { values, decision: undefined }
 }
 
 // ---------------------------------------------------------------------------
@@ -283,17 +365,20 @@ export const loop: {
 
               const { values, decision } = partitionChunk(chunk)
 
-              if (decision !== undefined) {
+              if (Option.isSome(decision)) {
                 yield* closeActive(active, Exit.void)
-                if (decision._tag === "Stop") {
+                if (decision.value._tag === "Stop" || decision.value._tag === "StopWith") {
+                  // `loop` has no next iteration to apply StopWith's state to;
+                  // the state lands in `loopFrom`'s outer ref or
+                  // `loopWithState`'s SubscriptionRef via their taps.
                   done = true
-                } else if (decision._tag === "Next") {
-                  state = decision.state
+                } else if (decision.value._tag === "Next") {
+                  state = decision.value.state
                 }
               }
 
               // Emit the values seen so far if any. Chunks from a Stream pull
-              // are non-empty, so when `decision === undefined` every event was
+              // are non-empty, so when `decision` is `None` every event was
               // a `Value` and `values` is non-empty here. With a decision and
               // no preceding values, fall through to the next iteration.
               if (isNonEmpty(values)) return values
@@ -306,6 +391,91 @@ export const loop: {
     ),
 )
 
+// ---------------------------------------------------------------------------
+// loopFrom - stream-driven sibling of loop. One input item runs a full
+// multi-turn inner loop.
+// ---------------------------------------------------------------------------
+
+type LoopFromBody<S, I, A, E, R> = (
+  state: S,
+  input: I,
+) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>
+
+/**
+ * Input-driven sibling of `loop`. For each item pulled from the input
+ * stream, runs an inner seed-driven `loop` whose body is
+ * `(s) => body(s, item)`. State is threaded across input items.
+ *
+ * **Per-input semantics — the body emits standard `Event<A, S>`:**
+ *   - `value(a)`: emit `a` downstream
+ *   - `next(s)`: re-run the body with the SAME input and new state `s`
+ *     (multi-turn within one input — e.g. multiple model turns + tool
+ *     calls for one document)
+ *   - `stop`: end this input's inner loop, advance to the next input
+ *     (state preserved)
+ *   - body stream ending without a decision: same as `stop` (advance)
+ *
+ * **Outer termination:** the input stream ending. To halt programmatically
+ * from within, end the input stream upstream (`Stream.takeWhile`, a
+ * `SubscriptionRef` gate, etc.). Reserving `stop` for per-item
+ * advancement is what makes the common "stream of documents, multi-turn
+ * conversation per document" shape readable.
+ *
+ * Dual: data-first `loopFrom(input, initial, body)` and data-last
+ * `input.pipe(loopFrom(initial, body))` both work.
+ */
+export const loopFrom: {
+  <S, I, A, E, R>(
+    initial: S,
+    body: LoopFromBody<S, I, A, E, R>,
+  ): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>
+  <S, I, A, E, R, EI, RI>(
+    input: Stream.Stream<I, EI, RI>,
+    initial: S,
+    body: LoopFromBody<S, I, A, E, R>,
+  ): Stream.Stream<A, E | EI, R | RI>
+} = Function.dual(
+  3,
+  <S, I, A, E, R, EI, RI>(
+    input: Stream.Stream<I, EI, RI>,
+    initial: S,
+    body: LoopFromBody<S, I, A, E, R>,
+  ): Stream.Stream<A, E | EI, R | RI> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const stateRef = yield* Ref.make<S>(initial)
+        return input.pipe(
+          Stream.flatMap((item) =>
+            Stream.unwrap(
+              Effect.gen(function* () {
+                const state = yield* Ref.get(stateRef)
+                // Capture Next states (and stopWith's final state) into the
+                // outer ref so the LAST state seen in this input's inner
+                // loop is what the next input starts from.
+                const wrappedBody = (s: S) => {
+                  const result = body(s, item)
+                  const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result
+                  return stream.pipe(
+                    Stream.tap((event) =>
+                      Match.value(event).pipe(
+                        Match.tags({
+                          Next: (e) => Ref.set(stateRef, e.state),
+                          StopWith: (e) => Ref.set(stateRef, e.state),
+                        }),
+                        Match.orElse(() => Effect.void),
+                      ),
+                    ),
+                  )
+                }
+                return loop(state, wrappedBody)
+              }),
+            ),
+          ),
+        )
+      }),
+    ),
+)
+
 // ---------------------------------------------------------------------------
 // loopWithState - same body protocol, plus a live state observable.
 // ---------------------------------------------------------------------------
@@ -343,7 +513,13 @@ export const loopWithState = <S, A, E, R>(
     const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>
       stream.pipe(
         Stream.tap((event) =>
-          event._tag === "Next" ? SubscriptionRef.set(stateRef, event.state) : Effect.void,
+          Match.value(event).pipe(
+            Match.tags({
+              Next: (e) => SubscriptionRef.set(stateRef, e.state),
+              StopWith: (e) => SubscriptionRef.set(stateRef, e.state),
+            }),
+            Match.orElse(() => Effect.void),
+          ),
         ),
       )
 

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/streaming/JSONL.ts

@@ -61,23 +61,17 @@ 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
@@ -85,11 +79,8 @@ export const parse =
  * 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))
+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))))

package/src/testing/MockMusicGenerator.ts

@@ -47,12 +47,10 @@ const makeService = (
           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 yield* new AiError.InvalidRequest({
+              provider: "mock",
+              raw: `MockMusicGenerator exhausted: ${scripted.length} results scripted, but call ${i + 1} was made`,
+            })
           }
           return scripted[i]!
         }),